Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

73.0 KB
Raw Blame
/**
 * Keeps this machine in step with its account's device key log (deviceLog.ts) and turns what the log
 * says into trust: every key the log leaves active is trusted here, through the same path a trust-group
 * member is (GroupSyncer), and every key a `remove` takes out is forgotten.
 *
 *  - register(): this machine's own key goes into the log, once per sign-in — so an existing sign-in,
 *    from before the log existed, joins it with no action from anyone.
 *  - refresh():  read the log from the head this machine already verified; verify every new entry.
 *    A backend that rewrote the log (a different entry at a position already verified) or rolled it
 *    back (a head older than one verified) FREEZES it here: no key is added from the log until someone
 *    looks at what changed and trusts it again (rebaseline). Removals still take effect.
 *  - gossip:     the head rides every `group_sync`, so two devices shown different logs find out, and a
 *    device that is behind is handed the entries it is missing (a removal the backend held back).
 *  - announce:   an `add` past the point this machine joined the log is a "New device: X" and stays
 *    `pending` until someone marks it seen — the one way a device added by whoever got hold of the
 *    account (or by the backend itself) is seen. Decided from the log alone, never from what the trust
 *    group already holds: a roster that outran the log must not hide it.
 *  - history:    what the log says about every add and remove, as this machine verified it.
 *  - confirm:    "It's mine" here (`dismiss` with `confirm`) is signed and shared beside the log
 *    (deviceAck.ts), and one another trusted device shared takes a key off `pending` here — so the person
 *    confirms a new device once, on any of their devices, not on every one.
 */
import {
  applyDevLogEntries, compareDevLogHead, DevLogError, devLogHash, devLogMessage, emptyDevLogState, nextDevLogEntry,
  parseDevLogEntry, signDevLogEntry, type DevLogEntry, type DevLogHead, type DevLogMember, type DevLogState,
} from './deviceLog.js'
import { checkDevAck, DEVACK_VERSION, signDevAck, type DevAck } from './deviceAck.js'
import {
  DEVLOG_DEPARTED, DEVLOG_RECENT, type DevLogConfirmed, type DevLogConflict, type DevLogDeparted, type DevLogFile, type DevLogFreeze,
  type DeviceLogStore,
} from './deviceLogStore.js'
import { devLogHistory, type DevLogHistoryRow } from './deviceHistory.js'
import { b64d, fingerprint, verify } from './core.js'

export interface DeviceLogFetched { acct: string; head: DevLogHead; entries: unknown[] }
export type DeviceLogAppendAnswer = { head: DevLogHead } | { error: string; head?: DevLogHead }

/** A sign-in by hand, as this machine's session records it (authSession `signInOf`) — never anything
 *  the backend sends. */
export interface DevLogSignIn {
  /** Which sign-in it is. */
  epoch: string
  /** Given to a session from before sign-ins were recorded, or a Team sign-in's (authSession `teamSignInEpoch`):
   *  nobody saw it being made by hand here, so it never starts the log over (it may take a file over). */
  adopted: boolean
  /** When it was made (ms); null when not known — then it never starts the log over either. */
  at: number | null
  /** The account it was made to, as the backend named it right after (authSession `signInAcct`); absent
   *  when that could not be asked (then only DEVLOG_RESET_WINDOW_MS opens the door), never for an
   *  adopted one. */
  acct?: string | null
}

/** How long after a sign-in by hand a read of another account may start the log over: past it, with
 *  no read of that account yet, the backend has had the time to pick when it says so. */
export const DEVLOG_RESET_WINDOW_MS = 10 * 60_000

export interface DeviceLogSyncerDeps {
  store: DeviceLogStore
  /** This machine's identity: base64 public key and the private key that signs for it. */
  identity: () => { pub: string; priv: Uint8Array }
  /** How this machine describes itself in the log; no machineId = not signed in, nothing to register. */
  self: () => { machineId: string | null; label: string }
  /** Which sign-in by hand this machine is under; null when not known. The log of another account is
   *  started (or a kept one restored) only when this changed AND the backend's account differs AND it is
   *  the account that sign-in was made to, or it was made less than DEVLOG_RESET_WINDOW_MS ago — never
   *  for an adopted one. Otherwise a different account id from the backend freezes the log. While the
   *  file is not this sign-in's yet (no read of it so far), what peers gossip is not taken either. */
  signIn: () => DevLogSignIn | null
  /** The log from `since`; null when the backend has none to give (an older backend, or unreachable). */
  fetch: (since: number) => Promise<DeviceLogFetched | null>
  /** Append one signed entry; null when the backend could not be reached. */
  append: (entry: DevLogEntry) => Promise<DeviceLogAppendAnswer | null>
  /** The acknowledgements ("It's mine", deviceAck.ts) of keys added after entry `since`, as the backend
   *  keeps them — unchecked: every one is judged here. null when there are none to read (a backend from
   *  before them answers 404, which is null too). Absent: none are ever read. */
  fetchAcks?: (since: number) => Promise<unknown[] | null>
  /** Keep one acknowledgement this machine signed; false when the backend did not take it. Absent: none
   *  is shared, and "It's mine" here stays here. */
  postAck?: (ack: DevAck) => Promise<boolean>
  /** This machine is moving from one account's log to another's (a sign-in by hand, or a review of the
   *  other account's list): put away what `from` trusted here and bring back what `to` did. Called before
   *  the new log is written, so what it snapshots as already trusted (`trustedNow`) is `to`'s. */
  switchAccount?: (from: string, to: string) => void
  /** Trust these keys here (and tell the trust group, so devices that predate the log learn of them). */
  adopt: (members: DevLogMember[]) => void
  /** Stop trusting a key here (and tombstone it in the trust group). */
  drop: (pub: string) => void
  /** The keys this machine trusts right now: snapshotted once, when it joins the log (or migrates to
   *  this version), so what it already knew then is never news. */
  trustedNow: () => string[]
  /** Whether the trust group holds a removal for `pub` that predates the log. */
  tombstoned: (pub: string) => boolean
  /** Whether this machine's user unpaired `pub` here — a local override the log never beats. */
  blocked: (pub: string) => boolean
  /** Whether `pub` may open a session here right now (it is paired). Given, every read of the log trusts
   *  again an active key that is not: one the adoption of its entry missed stays trusted by no one. */
  isTrusted?: (pub: string) => boolean
  /** A key joined the log after this machine did: "New device: X". */
  announce: (member: DevLogMember) => void
  /** A device was taken out of the log after this machine joined (not by this machine). */
  removed?: (notice: DeviceRemovalNotice) => void
  /** Another key holds this machine's id in the log (first time that holder is seen). */
  conflict?: (conflict: DevLogConflict) => void
  /** A fork split the lists: stop trusting these keys here until `rebaseline`. */
  suspend?: (pubs: string[]) => void
  /** `rebaseline` cleared the suspension: trust the roster again. */
  resume?: () => void
  /** This machine's own key was removed from the log: it is signed out. */
  signedOut: () => void
  /** When each key last opened a session or read the log, from the backend; null when it could not
   *  be asked. Only `sweepStale` reads it. */
  seen?: () => Promise<DeviceKeysSeen | null>
  /** Something a window shows changed (the list, the frozen line). */
  changed?: () => void
  log?: (line: string) => void
  now?: () => number
  sleep?: (ms: number) => Promise<void>
}

export interface DeviceLogListing {
  head: DevLogHead | null
  frozen: DevLogFreeze | null
  self: string
  /** `confirmed`: another trusted device said "It's mine" for it while it was new here — which, and when. */
  members: Array<DevLogMember & { fingerprint: string; self: boolean; firstSeen?: number; pending: boolean; suspended: boolean; confirmed?: DevLogConfirmed }>
  /** Machines whose own copy of the log is frozen, as their last `group_sync` said. */
  frozenPeers: string[]
  /** Keys that joined after this machine did and nobody has marked as seen. */
  pending: string[]
  /** Keys not trusted here after a fork, until `rebaseline`. */
  suspended: string[]
  joinedSeq: number
  /** The keys that were on the account before this machine joined (the "Already on your account" list):
   *  active, not this machine, at or before `joinedSeq` — plus any key this machine already trusted at
   *  joining whose entry came after it (a log cut short at the first read must not hide it). */
  baseline: string[]
  /** false until the "already on your account" list was acknowledged. */
  baselineSeen: boolean
  /** Another key holds this machine's id (and still does). */
  conflict: DevLogConflict | null
  /** New keys removed before anyone marked them as seen: flagged until dismissed (oldest first). */
  departed: DevLogDeparted[]
  /** Why the backend last refused this machine's own key (`TOO_MANY`, …), until a register gets through.
   *  Without it a refusal only reached the daemon's log, and the machine just stayed "not registered". */
  registerError?: string
}

/** A device taken out of the account's log after this machine joined it. */
export interface DeviceRemovalNotice {
  pub: string
  label: string
  kind: DevLogMember['kind']
  fingerprint: string
  signer: string
  signerLabel: string
  signerFingerprint: string
  /** The signer is itself a new device nobody has looked at. */
  signerPending: boolean
  /** The device removed itself (signed out). */
  selfRemoved: boolean
  at: number
}

export interface DeviceLogHistory {
  rows: DevLogHistoryRow[]
  /** false when only part of the log could be read (offline). */
  complete: boolean
  frozen: DevLogFreeze | null
}

/** What `trustFromLog` made of a key: trusted, or why not. */
export type DeviceLogTrustOutcome = 'trusted' | 'self' | 'absent' | 'suspended' | 'blocked' | 'tombstoned' | 'frozen' | 'unavailable'

export type DeviceLogRemoveResult = { ok: true } | { ok: false; error: 'NOT_ACTIVE' | 'NOT_IN_LOG' | 'UNAVAILABLE' | 'REFUSED'; detail?: string }

/** `rebaseline(confirm, head)` refused: the backend's list is no longer the one that was previewed
 *  (`LOG_CHANGED`), or it is another account's while the log this machine keeps is the one of the
 *  sign-in it is under (`OTHER_ACCOUNT`: only a sign-in switches accounts). */
export interface DeviceLogRebaselineChanged { error: 'LOG_CHANGED' | 'OTHER_ACCOUNT' }

export interface DeviceLogRebaseline {
  head: DevLogHead
  added: DevLogMember[]
  removed: DevLogMember[]
}

const APPEND_ATTEMPTS = 5
const PAGES = 20
/** The page cap of a first read of a log (and of a review): 100,000 entries. At PAGES a log past 10,000
 *  entries ended its join part-way, and every key after the cut was announced as a new device. */
const JOIN_PAGES = 200
/** `sweepStale`: an app key unused this long, and added at least this long ago, is taken out of the log —
 *  a browser whose storage was cleared, an app reinstalled, never comes back for its key, and at 256
 *  active keys (DEVLOG_MAX_ACTIVE) no new device can join the account. */
export const STALE_AFTER_MS = 180 * 24 * 60 * 60_000
/** When each key was last used (ms, by pub), and since when that record runs (null: unknown). A key with
 *  no time is unused only if the record is older than the question: a Redis that came back empty once
 *  read as "no app used in months", and the sweep would have removed every old app key. */
export interface DeviceKeysSeen { seen: Record<string, number>; since: number | null }
/** At most one sweep per this long on a machine; the timer that offers it runs every 10 minutes. */
const SWEEP_EVERY_MS = 6 * 60 * 60_000
/** At most this many removals per sweep (the next one goes on), each SWEEP_GAP_MS apart: the backend
 *  takes 10 appends a minute from a machine, and a person's own `devices remove` must still get through. */
const SWEEP_MAX = 20
const SWEEP_GAP_MS = 10_000
/** How much later each next machine (by key order) takes over a sweep the ones before it have not done. */
const SWEEP_TURN_MS = 24 * 60 * 60_000
/** The newest hashes a `group_sync` carries, so a fork can be located. */
const GOSSIP_HASHES = 64

interface Known { label: string; kind: DevLogMember['kind'] }

const fp = (pub: string): string => fingerprint(b64d(pub))
const day = (ms: number): string => new Date(ms).toISOString().slice(0, 10)
const uniq = (xs: readonly string[]): string[] => [...new Set(xs)]

/**
 * Where a peer's log first differs from `state`: the first seq, in the window of hashes the peer sent
 * (`theirs.hashes`, with `theirs.head` the last of them), whose hash is not ours — only when the entry
 * before it matches (or it is the first), so the split is proven rather than guessed. null when the peer
 * sent no usable hashes, nothing in the shared window differs, or the split lies before the window.
 */
export function devLogDivergence(state: DevLogState, theirs: unknown): number | null {
  if (!theirs || typeof theirs !== 'object') return null
  const { head, hashes } = theirs as { head?: { seq?: unknown; hash?: unknown }; hashes?: unknown }
  if (!Array.isArray(hashes) || !hashes.length || hashes.length > 4 * GOSSIP_HASHES) return null
  const window = new Map<number, string>()
  let prev = 0
  for (const h of hashes) {
    if (!h || typeof h !== 'object') return null
    const { seq, hash } = h as { seq?: unknown; hash?: unknown }
    if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 1 || typeof hash !== 'string' || hash.length > 128) return null
    if (prev !== 0 && seq !== prev + 1) return null
    prev = seq
    window.set(seq, hash)
  }
  // The window must end where the peer's head is, or it describes some other log.
  if (!head || head.seq !== prev || head.hash !== window.get(prev)) return null
  const first = Math.min(...window.keys())
  for (const [seq, hash] of window) {
    if (seq > state.head.seq || state.hashes[seq - 1] === hash) continue
    if (seq === 1) return 1
    if (seq === first) return null
    return state.hashes[seq - 2] === window.get(seq - 1) ? seq : null
  }
  return null
}

export class DeviceLogSyncer {
  private readonly now: () => number
  private readonly sleep: (ms: number) => Promise<void>
  private refreshing: Promise<void> | null = null
  private readonly frozenPeers = new Map<string, boolean>()
  private readonly removing = new Set<string>()
  private readonly inFlightRemovals = new Map<string, Promise<DeviceLogRemoveResult>>()
  /** The history walk in progress, which a second `history()` joins. */
  private historying: Promise<DeviceLogHistory> | null = null
  /** Every entry fetched for the history so far (seq 1..n), this run only: never written to disk. */
  private histCache: { acct: string; entries: DevLogEntry[] } | null = null
  /** Why the backend last refused this machine's own key; this run only (the file format stays as older
   *  versions read it). */
  private registerError: string | null = null
  /** When `sweepStale` last ran here (ms); this run only. */
  private lastSweep: number | null = null

  constructor(private readonly deps: DeviceLogSyncerDeps) {
    this.now = deps.now ?? (() => Date.now())
    this.sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
  }

  /** Read the log and put this machine's own key into it. Never throws. */
  async register(): Promise<void> {
    try {
      const self = this.deps.self()
      if (!self.machineId) return
      await this.refresh()
      const { pub, priv } = this.deps.identity()
      for (let attempt = 0; attempt < APPEND_ATTEMPTS; attempt++) {
        const file = this.marks()
        const state = file.state
        if (!state || file.frozen) return
        if (state.removed.includes(pub)) { this.deps.signedOut(); return }
        const mine = state.active[pub]
        if (mine) {
          this.registerError = null
          this.clearConflict()
          if (mine.label === self.label || mine.machineId !== self.machineId) return
        } else {
          const taken = Object.values(state.active).find((m) => m.kind === 'machine' && m.machineId === self.machineId)
          if (taken) { this.noteConflict(file, taken); return }
        }
        const entry = signDevLogEntry(nextDevLogEntry(state, {
          op: 'add', pub, kind: 'machine', machineId: self.machineId, label: self.label, signer: pub,
        }, this.now()), priv)
        const answer = await this.deps.append(entry)
        if (!answer) return
        if ('head' in answer && !('error' in answer)) { this.registerError = null; await this.refresh(); return }
        if (answer.error !== 'STALE_HEAD') {
          this.registerError = answer.error
          this.deps.log?.(`[devlog] register refused: ${answer.error}`)
          this.deps.changed?.()
          return
        }
        await this.refresh()
        await this.sleep(200 + Math.floor(Math.random() * 800) * (attempt + 1))
      }
    } catch (err) {
      this.deps.log?.(`[devlog] register failed: ${err instanceof Error ? err.message : String(err)}`)
    }
  }

  /** Read and verify whatever the log gained. Concurrent calls share one read. Never throws. */
  refresh(): Promise<void> {
    if (this.refreshing) return this.refreshing
    this.refreshing = this.doRefresh()
      .catch((err) => { this.deps.log?.(`[devlog] refresh failed: ${err instanceof Error ? err.message : String(err)}`) })
      .finally(() => { this.refreshing = null })
    return this.refreshing
  }

  /**
   * Read the log now and trust `pub` if it is on it: a hello from a key not paired here may be a device
   * that joined the account after this machine last read the log (a browser signed in before this machine
   * did), and without this it is denied until the next scheduled read. Says why not otherwise. Never throws.
   */
  async trustFromLog(pub: string): Promise<DeviceLogTrustOutcome> {
    try {
      // A read already on its way may have fetched before this key was added: wait for it, then read again.
      const earlier = this.refreshing
      await this.refresh()
      if (earlier) await this.refresh()
      const file = this.deps.store.read()
      if (file.frozen) return 'frozen'
      const state = file.state
      if (!state) return 'unavailable'
      const member = state.active[pub]
      if (!member) return 'absent'
      if (pub === this.deps.identity().pub) return 'self'
      if (this.suspendedKeys().includes(pub)) return 'suspended'
      if (this.deps.blocked(pub)) return 'blocked'
      if (this.deps.tombstoned(pub)) return 'tombstoned'
      this.trustState(state, [member])
      return 'trusted'
    } catch (err) {
      this.deps.log?.(`[devlog] could not read the log for a key: ${err instanceof Error ? err.message : String(err)}`)
      return 'unavailable'
    }
  }

  /** The file, with the joined point filled in for one written before it existed (or by a client that
   *  dropped it): everything up to what was already announced is then known, as it was. */
  private marks(): DevLogFile {
    const file = this.deps.store.read()
    if (!file.state || file.joinedSeq !== undefined) return file
    const next: DevLogFile = {
      ...file, joinedSeq: file.notifiedUpTo, preLog: this.deps.trustedNow(), pending: [], announced: [], baselineSeen: true,
    }
    this.deps.store.write(next)
    return next
  }

  /** Whether `local` — a sign-in by hand the file is not yet the log of — may start it over for another
   *  account: never an adopted one, and only shortly after it was made. A backend that holds back the
   *  log after a sign-in must not keep that door open, to name another account days later. */
  private mayStartOver(local: DevLogSignIn): boolean {
    return !local.adopted && local.at !== null && Math.abs(this.now() - local.at) <= DEVLOG_RESET_WINDOW_MS
  }

  /** Whether the trust group may swap rosters now: the log is this sign-in's (or none was read yet) and
   *  not frozen on an account it was not signed in to. Before that the roster here may still be the
   *  account this machine just left, and handing it out would carry its devices into the new one. */
  current(): boolean {
    const file = this.deps.store.read()
    return !file.state || (this.ownsFile(file) && file.frozen?.reason !== 'invalid')
  }

  /** Whether the file is the log of the sign-in this machine is under (or that cannot be told). Until a
   *  read of it under a new sign-in, it may be another account's: what a peer says is not judged
   *  against it — a peer of the new account would read as a fork of the old one. */
  private ownsFile(file: DevLogFile): boolean {
    const local = this.deps.signIn()
    return local === null || file.owner === local.epoch
  }

  private archiveDeparting(file: DevLogFile): void {
    const epoch = this.deps.signIn()?.epoch ?? ''
    // Team agents must not inherit the departing owner's device names, keys or trust decisions.
    this.deps.store.archive(file, { forget: epoch.startsWith('team:') || epoch.startsWith('adopted:team:') })
  }

  /** `file`, with every key a fork suspended in another account's kept log, and active in this one,
   *  suspended (and new) here as well: it is not trusted either way, so the list says so — and "It's
   *  mine" lifts it, everywhere (a review of this list does not: it never showed that suspension). */
  private carrySuspensions(file: DevLogFile): DevLogFile {
    const state = file.state
    if (!state) return file
    const selfPub = this.deps.identity().pub
    const current = file.suspended ?? []
    const carried = this.deps.store.archivedSuspended().filter((k) => !!state.active[k] && k !== selfPub && !current.includes(k))
    if (!carried.length) return file
    return { ...file, suspended: [...current, ...carried], pending: uniq([...(file.pending ?? []), ...carried]) }
  }

  /** `gone`, just taken out by `e`, kept flagged: it was new here and nobody had looked at it yet. */
  private departedOf(gone: DevLogMember, e: DevLogEntry, signerLabel: string): DevLogDeparted {
    return {
      pub: gone.pub, label: gone.label, kind: gone.kind, machineId: gone.machineId, fingerprint: fp(gone.pub), addedAt: gone.addedAt,
      removedAt: e.at, removedBy: e.signer, removedByLabel: signerLabel, selfRemoved: e.signer === gone.pub,
    }
  }

  /** `prev` plus `more` (a key once, at its newest), the oldest dropped past DEVLOG_DEPARTED. */
  private withDeparted(prev: DevLogDeparted[] | undefined, more: readonly DevLogDeparted[]): { departed?: DevLogDeparted[] } {
    if (!more.length) return prev ? { departed: prev } : {}
    const pubs = new Set(more.map((d) => d.pub))
    return { departed: [...(prev ?? []).filter((d) => !pubs.has(d.pub)), ...more].slice(-DEVLOG_DEPARTED) }
  }

  /** What a review (`rebaseline --yes`) takes out that was new here and never looked at: a key pending
   *  in `base` that the reviewed list does not keep — and a key the list added and removed again at
   *  entries this machine never verified (while it was frozen) — stays flagged as departed. */
  private reviewDeparted(
    base: DevLogFile, next: DevLogState, parsed: readonly DevLogEntry[], removed: readonly DevLogMember[], selfPub: string, preLog: ReadonlySet<string>,
  ): DevLogDeparted[] {
    const verified = base.state
    if (!verified) return []
    const pending = base.pending ?? []
    const known = new Map<string, Known>()
    const adds = new Map<string, DevLogEntry>()
    const out = new Map<string, DevLogDeparted>()
    for (const e of [...parsed].sort((a, b) => a.seq - b.seq)) {
      if (e.op === 'add') {
        if (!known.has(e.pub)) adds.set(e.pub, e) // added (not renamed)
        known.set(e.pub, { label: e.label, kind: e.kind })
        continue
      }
      const was = removed.find((m) => m.pub === e.pub)
      const add = adds.get(e.pub)
      const label = known.get(e.pub)?.label
      known.delete(e.pub)
      if (e.pub === selfPub || next.active[e.pub]) continue
      // Added at an entry this machine never verified, and gone again before it could see it.
      const unseen = !was && !!add && verified.hashes[add.seq - 1] !== devLogHash(add) && !preLog.has(e.pub) && !this.deps.blocked(e.pub)
      if ((was && pending.includes(e.pub)) || unseen) {
        const member: DevLogMember = was ?? { pub: e.pub, kind: add!.kind, machineId: add!.machineId, label: label ?? add!.label, addedAt: add!.at, seq: add!.seq }
        out.set(e.pub, this.departedOf(member, e, known.get(e.signer)?.label ?? ''))
      }
    }
    // Pending here, and not on the reviewed list at all (a branch the backend no longer serves).
    for (const m of removed) {
      if (out.has(m.pub) || m.pub === selfPub || !pending.includes(m.pub)) continue
      out.set(m.pub, {
        pub: m.pub, label: m.label, kind: m.kind, machineId: m.machineId, fingerprint: fp(m.pub), addedAt: m.addedAt,
        removedAt: this.now(), removedBy: '', removedByLabel: '', selfRemoved: false,
      })
    }
    return [...out.values()]
  }

  /** The first read of the log has reached its head (or stopped): what is verified from here on is news. */
  private endJoin(): void {
    const file = this.deps.store.read()
    if (!file.joining) return
    const { joining: _j, ...rest } = file
    this.deps.store.write(rest)
  }

  /** Another key holds this machine's id: remember it, and say so the first time that holder is seen. */
  private noteConflict(file: DevLogFile, holder: DevLogMember): void {
    if (file.conflict?.pub === holder.pub) return
    const conflict: DevLogConflict = {
      pub: holder.pub, label: holder.label, machineId: holder.machineId, addedAt: holder.addedAt, seq: holder.seq,
      fingerprint: fp(holder.pub), afterJoin: holder.seq > (file.joinedSeq ?? 0),
    }
    this.deps.store.write({ ...file, conflict })
    const who = `${conflict.label || '(no name)'} (${conflict.fingerprint})`
    this.deps.log?.(conflict.afterJoin
      ? `[devlog] ⚠ another key took this computer's place on your account after it joined: ${who} — if you did not set up Harness here again, remove that key from another device now`
      : `[devlog] this computer is held by another key on your account: ${who} — if that was an earlier install of this computer, remove it from another device; this computer joins on its own once it is gone`)
    this.deps.conflict?.(conflict)
    this.deps.changed?.()
  }

  private clearConflict(): void {
    const file = this.deps.store.read()
    if (!file.conflict) return
    const { conflict: _gone, ...rest } = file
    this.deps.store.write(rest)
    this.deps.changed?.()
  }

  private async doRefresh(): Promise<void> {
    try {
      await this.readPages()
    } finally {
      // However the read ended — at the head, on a freeze, or cut short (no answer, the page cap) — the
      // first read of a log is over: what is verified from here on is news. Held open, a backend that
      // stalls the second page would have every key it adds later taken for one there at joining.
      this.endJoin()
    }
    this.reconcile()
    // After the entries, so a key added and confirmed while this machine was away is first announced, as
    // every new key is — the one-time "New device: X" never waits on, or is skipped for, anyone's word —
    // and only then taken off the list.
    await this.applyAcks()
  }

  /**
   * Trust again every key the log leaves active that is not trusted here. A key is adopted as its entry is
   * verified, and only then: the head is written first, so an adoption that threw, a process that died in
   * between, or a roster that already held the member (nothing new to merge, so nothing trusted) left it
   * untrusted for good — its device saw "Link required" however often it came back. Never announces: what
   * is news was decided when the entry was read. Never throws.
   */
  private reconcile(): void {
    const isTrusted = this.deps.isTrusted
    if (!isTrusted) return
    try {
      const file = this.deps.store.read()
      const state = file.state
      if (file.frozen || !state) return
      const selfPub = this.deps.identity().pub
      const missing = Object.values(state.active).filter((m) => m.pub !== selfPub && !isTrusted(m.pub))
      const adopted = this.trustState(state, missing)
      if (adopted.length) this.deps.log?.(`[devlog] trusting ${adopted.length} key(s) the log has and this machine did not: ${adopted.map((m) => fp(m.pub)).join(', ')}`)
    } catch (err) {
      this.deps.log?.(`[devlog] could not trust what the log has: ${err instanceof Error ? err.message : String(err)}`)
    }
  }

  private async readPages(): Promise<void> {
    this.marks()
    // The first read of a log (a new install, or an existing sign-in from before the log existed) only
    // learns what is there: every key it adopts, and none of it is news (it is before `joinedSeq`).
    let bootstrap = !this.deps.store.read().state?.head.seq
    // The cap is read each page: a first read only learns what is there, so it may go far; once it is
    // over (`endJoin`, unconditional below) a stalled or endless backend gets the usual PAGES.
    for (let page = 0; page < (this.deps.store.read().joining ? JOIN_PAGES : PAGES); page++) {
      const file = this.deps.store.read()
      const since = file.state?.head.seq ?? 0
      const got = await this.deps.fetch(since)
      if (!got) return
      // A head that is not a position is the backend lying (or broken): nothing to verify it against.
      if (!Number.isSafeInteger(got.head.seq) || got.head.seq < 0) return
      const latest = this.deps.store.read()
      const now = latest.state
      if (file.state && now && now.acct === got.acct
        && (file.state.acct !== now.acct || file.state.head.seq !== now.head.seq || file.state.head.hash !== now.head.hash)) {
        // The log moved here while this page was on its way (a peer handed over its tail): judged
        // against the newer head the page would read as a rollback, or as entries out of order. Ask
        // again from where the log is now.
        continue
      }
      const local = this.deps.signIn()
      let reset = !now
      if (now) {
        const signedInAgain = local !== null && latest.owner !== local.epoch
        if (now.acct !== got.acct) {
          // Another account only after a sign-in by hand here: the account it was made to, whenever; with
          // none recorded, any one right after it. Otherwise it is the backend saying so — and starting
          // over would clear every mark a fork put on the list, the real log then adopted whole.
          if (!signedInAgain || (local.acct ? local.acct !== got.acct : !this.mayStartOver(local))) {
            this.freeze('invalid')
            return
          }
          reset = true
        } else if (signedInAgain) {
          // Signed in again to the same account: the same list, now this sign-in's.
          this.deps.store.write({ ...latest, owner: local.epoch })
        }
      }
      if (reset) {
        if (now) {
          // Ordinary sign-ins keep the departing trust and log; Team sign-ins discard them.
          this.deps.switchAccount?.(now.acct, got.acct)
          this.archiveDeparting(latest)
        }
        // Back to an account this machine was signed in to before: its log as verified then, and every
        // mark on it (frozen, suspended, pending), go on from where they were.
        const kept = this.deps.store.restore(got.acct, (k) => this.carrySuspensions({ ...k, ...(local ? { owner: local.epoch } : {}) }))
        if (kept) {
          bootstrap = !kept.state?.head.seq
          continue
        }
        // First read, or signed in to another account here: that account's log starts from nothing.
        // `joinedSeq` starts at 0 and follows the head of each page this machine VERIFIES (accept):
        // never the head the backend merely claims, or it could park it far ahead and have every key
        // it forges below that adopted without a word. `preLog` is what was trusted already.
        const fresh: DevLogFile = {
          state: emptyDevLogState(got.acct), recent: [], frozen: null, notifiedUpTo: 0,
          joinedSeq: 0, preLog: this.deps.trustedNow(), pending: [], announced: [], suspended: [], baselineSeen: false,
          joining: true, ...(local ? { owner: local.epoch } : {}),
        }
        this.deps.store.write(fresh)
        bootstrap = true
        if (got.head.seq === 0) return
        if (since !== 0) continue
      }
      const current = this.deps.store.read()
      const state = current.state!
      // A log frozen as `invalid` from a page that claimed a head past the entries it carried heals by itself once the
      // backend serves them: the backend did that whenever a device registered between its two reads, and froze every
      // device that read at that moment until someone ran `harness devices rebaseline` (#1789, fixed 2026-10-27; a Mac
      // frozen on 10-24 could never link its Harness Team account). The entries must continue the chain this machine
      // verified and check out one by one (`accept`), or it stays frozen. A rollback or a fork never heals on its own.
      const heals = current.frozen?.reason === 'invalid' && got.head.seq > state.head.seq && got.entries.length > 0
      if (current.frozen && !heals) { this.looseRemovals(got.entries); return }
      if (got.head.seq < state.head.seq) { this.freeze('rollback'); return }
      if (got.head.seq === state.head.seq) {
        if (got.head.hash !== state.head.hash) this.freeze('fork')
        return
      }
      if (!got.entries.length) { this.freeze('invalid'); return }
      if (!this.accept(got.entries, bootstrap)) return
      if (heals) this.deps.log?.('[devlog] the device list checks out again: no longer frozen')
      if (this.deps.store.read().state!.head.seq >= got.head.seq) return
    }
  }

  /** `firstSeen` plus now for each newly applied key, minus keys no longer active (keeps the file small). */
  private stamp(prev: Record<string, number> | undefined, added: readonly DevLogMember[], state: DevLogState): Record<string, number> {
    const at = this.now()
    const out: Record<string, number> = {}
    for (const pub of Object.keys(state.active)) {
      const t = prev?.[pub] ?? (added.some((m) => m.pub === pub) ? at : undefined)
      if (t !== undefined) out[pub] = t
    }
    return out
  }

  /** `keys` cut to the ones still active — the marks never outlive the key. */
  private prune(keys: readonly string[] | undefined, state: DevLogState): string[] {
    return uniq(keys ?? []).filter((k) => state.active[k] !== undefined)
  }

  /** The confirmed marks of keys still active, as a file field (none when there are none). */
  private keptConfirmed(marks: Record<string, DevLogConfirmed> | undefined, state: DevLogState): { confirmed?: Record<string, DevLogConfirmed> } {
    const kept = Object.entries(marks ?? {}).filter(([k]) => state.active[k] !== undefined)
    return kept.length ? { confirmed: Object.fromEntries(kept) } : {}
  }

  /**
   * Take off `pending` every key another of the person's trusted devices said "It's mine" for
   * (deviceAck.ts), and remember which device did ("Confirmed on <label>").
   *
   * The backend's word counts for nothing: each acknowledgement must check out against the log as THIS
   * machine verified it (signature, a signer active on it, the key added at the entry it names), and
   * against this machine's own marks. The key must still be new here and not suspended — an
   * acknowledgement never lifts a suspension; only the person does, on this machine, with "It's mine" on
   * that very device. The signer must be a device this machine trusts: not new here itself (two new
   * devices must not vouch for each other), not suspended, not removed (a departed key is not active),
   * not unpaired or tombstoned here, and not this machine (its own "It's mine" already took the key off).
   * Nothing is read while the log is frozen or not yet this sign-in's. Never throws.
   */
  private async applyAcks(): Promise<void> {
    const fetchAcks = this.deps.fetchAcks
    if (!fetchAcks) return
    try {
      const candidates = this.ackable(this.deps.store.read())
      // Nothing new here: nothing to ask (and no request at all, on every read, for most of a device's life).
      if (!candidates.length) return
      const raw = await fetchAcks(Math.min(...candidates.map((m) => m.seq)) - 1)
      if (!raw?.length) return
      // Judged against the file as it is NOW: the log may have moved, or a key been looked at, meanwhile.
      const file = this.deps.store.read()
      const state = file.state
      const open = new Set(this.ackable(file).map((m) => m.pub))
      if (!state || !open.size) return
      const selfPub = this.deps.identity().pub
      const pending = new Set(file.pending ?? [])
      const suspended = new Set(this.suspendedKeys())
      const confirmed: Record<string, DevLogConfirmed> = {}
      for (const r of raw) {
        const checked = checkDevAck(state, r)
        if (!checked.ok) continue
        const { ack } = checked
        if (!open.has(ack.pub) || confirmed[ack.pub]) continue
        if (ack.signer === selfPub || pending.has(ack.signer) || suspended.has(ack.signer)
          || this.deps.blocked(ack.signer) || this.deps.tombstoned(ack.signer)) continue
        confirmed[ack.pub] = { by: ack.signer, label: state.active[ack.signer].label, at: this.now() }
      }
      const pubs = Object.keys(confirmed)
      if (!pubs.length) return
      this.deps.store.write({
        ...file,
        pending: (file.pending ?? []).filter((k) => !confirmed[k]),
        ...this.keptConfirmed({ ...file.confirmed, ...confirmed }, state),
      })
      for (const pub of pubs) {
        const c = confirmed[pub]
        this.deps.log?.(`[devlog] ${state.active[pub].label || '(no name)'} (${fp(pub)}) was confirmed as yours on ${c.label || 'another device'} (${fp(c.by)}): no longer new here`)
      }
      this.deps.changed?.()
    } catch (err) {
      // The list stays as it was; the next read asks again.
      this.deps.log?.(`[devlog] could not read which devices were confirmed: ${err instanceof Error ? err.message : String(err)}`)
    }
  }

  /** The keys an acknowledgement could take off `pending` in `file`: new here, still active, not
   *  suspended, not this machine — and none at all from a log that is frozen or not this sign-in's. */
  private ackable(file: DevLogFile): DevLogMember[] {
    const state = file.state
    if (!state || file.frozen || !this.ownsFile(file)) return []
    const selfPub = this.deps.identity().pub
    const suspended = new Set(this.suspendedKeys())
    return uniq(file.pending ?? []).map((k) => state.active[k]).filter((m): m is DevLogMember => !!m && m.pub !== selfPub && !suspended.has(m.pub))
  }

  /** The notice for a `remove` that took `gone` out, or null when there is nothing to say: this
   *  machine's own removal, this machine's own key, or a removal from before it joined. `known` says
   *  what each key was called, and what kind it was, BEFORE this removal — the remove entry's own label
   *  and kind are the signer's to pick, so they are never what the person is told. */
  private removalNotice(e: DevLogEntry, joinedSeq: number, selfPub: string, pending: readonly string[], known: ReadonlyMap<string, Known>): DeviceRemovalNotice | null {
    if (e.op !== 'remove' || e.seq <= joinedSeq || e.pub === selfPub || e.signer === selfPub) return null
    const was = known.get(e.pub)
    return {
      pub: e.pub, label: was?.label ?? e.label, kind: was?.kind ?? e.kind, fingerprint: fp(e.pub),
      signer: e.signer, signerLabel: known.get(e.signer)?.label ?? '', signerFingerprint: fp(e.signer),
      signerPending: pending.includes(e.signer), selfRemoved: e.signer === e.pub, at: this.now(),
    }
  }

  /** What each active key in `state` is called now, to be walked forward through entries. */
  private knownOf(state: DevLogState): Map<string, Known> {
    return new Map(Object.values(state.active).map((m) => [m.pub, { label: m.label, kind: m.kind }] as const))
  }

  /** Apply entries that continue this machine's log; freeze on anything that does not. */
  private accept(entries: readonly unknown[], bootstrap: boolean): boolean {
    const file = this.marks()
    // While the first read of this log is open (a peer's tail can arrive between its pages too):
    // whatever is verified before it reaches the head is what was there at joining.
    const joining = file.joining === true
    let applied
    try {
      applied = applyDevLogEntries(file.state!, entries)
    } catch (err) {
      if (!(err instanceof DevLogError)) throw err
      this.freeze(err.code === 'BROKEN_CHAIN' || err.code === 'OUT_OF_ORDER' ? 'fork' : 'invalid')
      return false
    }
    const selfPub = this.deps.identity().pub
    // While joining, everything this page verified is what was there before: the joined point moves up
    // to the verified head (never past it), and none of it is news.
    const joinedSeq = joining ? applied.state.head.seq : file.joinedSeq ?? 0
    const preLog = new Set(file.preLog ?? [])
    const parsed = entries.map((e) => parseDevLogEntry(e)).filter((e): e is DevLogEntry => e !== null)
    // News is decided from the log alone: an `add` past the point this machine joined, for a key it
    // did not already trust then. What the roster or the pins hold now says nothing — a key can reach
    // them (over `group_sync`) before this machine reads the entry that adds it.
    const news = applied.added.filter((m) =>
      m.seq > joinedSeq && m.pub !== selfPub && !preLog.has(m.pub) && !this.deps.blocked(m.pub))
    const pendingBefore = file.pending ?? []
    const announced = file.announced ?? []
    const newHere = [...pendingBefore, ...news.map((m) => m.pub)]
    const pending = this.prune(newHere, applied.state)
    const toAnnounce = news.filter((m) => !announced.includes(m.pub))
    // Walk the entries in order: a removal is described by what the key was called when it was removed.
    const known = this.knownOf(file.state!)
    const notices: DeviceRemovalNotice[] = []
    const gone = new Map(applied.removed.map((m) => [m.pub, m] as const))
    const departed: DevLogDeparted[] = []
    for (const e of [...parsed].sort((a, b) => a.seq - b.seq)) {
      if (e.op === 'add') known.set(e.pub, { label: e.label, kind: e.kind })
      else {
        const n = this.removalNotice(e, joinedSeq, selfPub, newHere, known)
        if (n) notices.push(n)
        // A new key nobody looked at, gone again (even within this page): it stays flagged.
        const member = gone.get(e.pub)
        if (member && newHere.includes(e.pub) && e.pub !== selfPub) departed.push(this.departedOf(member, e, known.get(e.signer)?.label ?? ''))
        known.delete(e.pub)
      }
    }
    // The holder of this machine's id left, or this machine got its own key in: the conflict is over.
    const conflictOver = !!file.conflict && (!!applied.state.active[selfPub] || !applied.state.active[file.conflict.pub])
    // A key taken into the "already on your account" list after that list was acknowledged: show it.
    const unseen = joining && file.baselineSeen !== false && applied.added.some((m) => m.pub !== selfPub)
    const { conflict: _c, confirmed: _k, ...rest } = file
    this.deps.store.write(this.carrySuspensions({
      ...rest,
      ...(unseen ? { baselineSeen: false } : {}),
      ...(file.conflict && !conflictOver ? { conflict: file.conflict } : {}),
      state: applied.state,
      joinedSeq,
      recent: [...file.recent, ...parsed].slice(-DEVLOG_RECENT),
      frozen: null,
      notifiedUpTo: applied.state.head.seq,
      firstSeen: this.stamp(file.firstSeen, applied.added.filter((m) => m.seq > joinedSeq), applied.state),
      pending,
      announced: this.prune([...announced, ...toAnnounce.map((m) => m.pub)], applied.state),
      suspended: this.prune(file.suspended, applied.state),
      ...this.withDeparted(file.departed, departed),
      ...this.keptConfirmed(file.confirmed, applied.state),
    }))
    this.trustState(applied.state, bootstrap ? Object.values(applied.state.active) : [...applied.added, ...applied.relabeled])
    for (const m of applied.removed) this.deps.drop(m.pub)
    for (const m of toAnnounce) this.deps.announce(m)
    for (const n of notices) this.deps.removed?.(n)
    if (applied.state.removed.includes(selfPub)) this.deps.signedOut()
    void this.carryOverTombstones(applied.state)
    this.deps.changed?.()
    // Its holder gone, this machine takes its own place in the account.
    if (conflictOver && !applied.state.active[selfPub]) void this.register()
    return true
  }

  /** Trust those of `members` the log leaves active and nothing here holds back; returns them. */
  private trustState(state: DevLogState, members: DevLogMember[]): DevLogMember[] {
    const selfPub = this.deps.identity().pub
    const suspended = this.suspendedKeys()
    const adopt = members.filter((m) => m.pub !== selfPub && state.active[m.pub] && !suspended.includes(m.pub)
      && !this.deps.blocked(m.pub) && !this.deps.tombstoned(m.pub))
    if (adopt.length) this.deps.adopt(adopt)
    return adopt
  }

  /** A removal made in the trust group before the log existed must not be undone by the log: this
   *  machine, holding that removal, writes it into the log. */
  private async carryOverTombstones(state: DevLogState): Promise<void> {
    const selfPub = this.deps.identity().pub
    if (!state.active[selfPub]) return
    for (const m of Object.values(state.active)) {
      if (m.pub !== selfPub && this.deps.tombstoned(m.pub) && !this.removing.has(m.pub)) await this.remove(m.pub)
    }
  }

  /** While frozen, a removal still counts — if a key this machine trusts signed it. A key a fork
   *  suspended is not trusted here, so what it signs does not count either. */
  private looseRemovals(entries: readonly unknown[]): void {
    const file = this.marks()
    const state = file.state
    if (!state) return
    const selfPub = this.deps.identity().pub
    const joinedSeq = file.joinedSeq ?? 0
    const suspended = new Set(file.suspended ?? [])
    const loose: DevLogEntry[] = []
    const notices: DeviceRemovalNotice[] = []
    const departed: DevLogDeparted[] = []
    const known = this.knownOf(state)
    for (const raw of entries) {
      const e = parseDevLogEntry(raw)
      if (!e || e.op !== 'remove' || !state.active[e.signer] || suspended.has(e.signer) || !state.active[e.pub]) continue
      if (!verify(b64d(e.signer), devLogMessage(e), b64d(e.sig))) continue
      const notice = this.removalNotice(e, joinedSeq, selfPub, file.pending ?? [], known)
      if ((file.pending ?? []).includes(e.pub) && e.pub !== selfPub) departed.push(this.departedOf(state.active[e.pub], e, known.get(e.signer)?.label ?? ''))
      delete state.active[e.pub]
      state.removed.push(e.pub)
      this.deps.drop(e.pub)
      loose.push(e)
      if (notice) notices.push(notice)
    }
    if (!loose.length) return
    this.deps.store.write({
      ...file, state,
      looseRemoved: [...(file.looseRemoved ?? []), ...loose],
      pending: this.prune(file.pending, state), announced: this.prune(file.announced, state), suspended: this.prune(file.suspended, state),
      ...this.withDeparted(file.departed, departed),
    })
    for (const n of notices) this.deps.removed?.(n)
    this.deps.changed?.()
  }

  private freeze(reason: DevLogFreeze['reason']): void {
    const file = this.deps.store.read()
    if (file.frozen || !file.state) return
    const { joining: _j, ...rest } = file
    this.deps.store.write({ ...rest, frozen: { reason, at: this.now(), lastGoodHead: file.state.head } })
    this.deps.log?.(`[devlog] FROZEN (${reason}): the device list the backend serves does not match what this machine verified — no device is added from it until someone reviews it (harness devices rebaseline)`)
    this.deps.changed?.()
  }

  /** Remove a device from the log (and so from every device). Signed by this machine. */
  remove(pub: string): Promise<DeviceLogRemoveResult> {
    // One removal per key at a time: taking it out here tombstones it in the trust group, which hands
    // it straight back through `onDropped` — that second ask joins this one.
    const running = this.inFlightRemovals.get(pub)
    if (running) return running
    this.removing.add(pub)
    // Started a tick later, once it is in the map: `removeOnce` drops the key before its first await, and
    // that drop's `onDropped` asks again at once — begun right away, the second ask found no entry and
    // appended its own removal, and this one came back NOT_IN_LOG for a key it had just taken out.
    const task = Promise.resolve().then(() => this.removeOnce(pub))
      .finally(() => { this.removing.delete(pub); this.inFlightRemovals.delete(pub) })
    this.inFlightRemovals.set(pub, task)
    return task
  }

  private async removeOnce(pub: string): Promise<DeviceLogRemoveResult> {
    const { pub: selfPub, priv } = this.deps.identity()
    for (let attempt = 0; attempt < APPEND_ATTEMPTS; attempt++) {
      const file = this.deps.store.read()
      const state = file.state
      if (!state) return { ok: false, error: 'UNAVAILABLE' }
      const target = state.active[pub]
      if (!target) return { ok: false, error: 'NOT_IN_LOG' }
      if (!state.active[selfPub]) return { ok: false, error: 'NOT_ACTIVE' }
      // Take effect here at once, whatever the backend does with it.
      this.deps.drop(pub)
      const entry = signDevLogEntry(nextDevLogEntry(state, {
        op: 'remove', pub, kind: target.kind, machineId: target.machineId, label: target.label, signer: selfPub,
      }, this.now()), priv)
      const answer = await this.deps.append(entry)
      if (!answer) return { ok: false, error: 'UNAVAILABLE' }
      if (!('error' in answer)) { await this.refresh(); return { ok: true } }
      if (answer.error !== 'STALE_HEAD') return { ok: false, error: 'REFUSED', detail: answer.error }
      await this.refresh()
      await this.sleep(200 + Math.floor(Math.random() * 800) * (attempt + 1))
    }
    return { ok: false, error: 'UNAVAILABLE' }
  }

  /**
   * Take out of the log the app keys nobody has used in STALE_AFTER_MS (and added that long ago too), at
   * most SWEEP_MAX at a time and one sweep per SWEEP_EVERY_MS. The machine whose key is the smallest of
   * the active machine keys goes first; each next one in that order waits a further SWEEP_TURN_MS before
   * it takes a key, so one machine does it with no coordination — and when that one is a build from before
   * the sweep (seen on a rollout: it never would) or is off, the next takes over a day later. Two that
   * both do get NOT_ACTIVE on the second removal, harmless. Never a machine key: when a machine was last used
   * is not something the backend can tell. Only on this sign-in's log, and never while it is frozen.
   * Never throws.
   *
   * ponytail: last-seen comes from the backend unverified, so a backend that lies about it can have a
   * machine remove an app key older than STALE_AFTER_MS (the removal is in every device's history, signed
   * by this machine). Upgrade path: a last-used time the app signs itself.
   */
  async sweepStale(): Promise<void> {
    try {
      const seen = this.deps.seen
      const now = this.now()
      if (!seen || (this.lastSweep !== null && now - this.lastSweep < SWEEP_EVERY_MS) || !this.current()) return
      const file = this.deps.store.read()
      const state = file.state
      if (!state || file.frozen) return
      const selfPub = this.deps.identity().pub
      const machines = Object.values(state.active).filter((m) => m.kind === 'machine').map((m) => m.pub).sort()
      const turn = machines.indexOf(selfPub)
      if (turn < 0) return
      this.lastSweep = now
      const got = await seen()
      // Not asked: try again on the next offer rather than read every key as never used.
      if (!got) { this.lastSweep = null; return }
      const cutoff = now - STALE_AFTER_MS - turn * SWEEP_TURN_MS
      const suspended = this.suspendedKeys()
      // A key with no time is unused only when the record has run since before the cutoff.
      const usedAt = (m: DevLogMember): number | null => {
        const t = got.seen[m.pub]
        return typeof t === 'number' && Number.isFinite(t) ? t : null
      }
      const unusedSinceCutoff = (m: DevLogMember): boolean => {
        const t = usedAt(m)
        return t !== null ? t < cutoff : got.since !== null && got.since < cutoff
      }
      const stale = Object.values(state.active)
        .filter((m) => m.kind === 'viewer' && m.pub !== selfPub && !suspended.includes(m.pub) && m.addedAt < cutoff && unusedSinceCutoff(m))
        .sort((a, b) => a.seq - b.seq)
        .slice(0, SWEEP_MAX)
      for (const [i, m] of stale.entries()) {
        if (i) await this.sleep(SWEEP_GAP_MS)
        const r = await this.remove(m.pub)
        // Already out of the log (another machine's sweep, a person's own removal): nothing to do.
        if (!r.ok && r.error === 'NOT_IN_LOG') continue
        if (!r.ok) { this.deps.log?.(`[devlog] could not remove unused device ${m.label || '(no name)'} (${fp(m.pub)}): ${r.detail ?? r.error}`); return }
        const t = usedAt(m)
        const when = t !== null ? `last used ${day(t)}` : `not used since ${day(got.since!)}`
        this.deps.log?.(`[devlog] removed unused device ${m.label || '(no name)'} (${fp(m.pub)}), ${when}`)
      }
    } catch (err) {
      this.deps.log?.(`[devlog] sweep failed: ${err instanceof Error ? err.message : String(err)}`)
    }
  }

  /**
   * What trusting the backend's log again would change; with `confirm`, do it. `expected` is the head
   * the person was shown in the preview: if the backend's log is not that one any more, nothing is
   * done (`LOG_CHANGED`) — what gets trusted is what was reviewed.
   */
  async rebaseline(confirm: boolean, expected?: DevLogHead): Promise<DeviceLogRebaseline | DeviceLogRebaselineChanged | null> {
    const entries: unknown[] = []
    let acct = ''
    let head: DevLogHead = emptyDevLogState('').head
    // A review reads the whole list, so a log past PAGES' worth can still be reviewed.
    for (let page = 0; page < JOIN_PAGES; page++) {
      const got = await this.deps.fetch(entries.length)
      if (!got) return null
      if (!Number.isSafeInteger(got.head.seq) || got.head.seq < 0) return null
      acct = got.acct
      head = got.head
      entries.push(...got.entries)
      if (!got.entries.length || entries.length >= got.head.seq) break
    }
    let next: DevLogState
    try {
      next = applyDevLogEntries(emptyDevLogState(acct), entries).state
    } catch { return null }
    if (next.head.seq !== head.seq || next.head.hash !== head.hash) return null
    const file = this.marks()
    const same = !!file.state && file.state.acct === next.acct
    // Another account's list while the live log is the one of the sign-in this machine is under: the
    // backend switched accounts on its own. A review must not move this machine there (the account it
    // is signed in to, and every mark on it, would go out of sight): only a sign-in switches accounts.
    // Only a sign-in by hand the file is not stamped with is that switch: none recorded, an adopted one
    // (a session this machine took over — whatever stamp the file has, or lacks, from an older version),
    // or the sign-in the file is stamped with is not.
    const local = this.deps.signIn()
    if (file.state && !same && (local === null || local.adopted || file.owner === local.epoch)) return { error: 'OTHER_ACCOUNT' }
    if (confirm && expected && (expected.seq !== next.head.seq || expected.hash !== next.head.hash)) return { error: 'LOG_CHANGED' }
    // The list under review is judged against this account's own log as this machine verified it:
    // the live file, or — for another account — the one kept when this machine left it (its marks go
    // on), or else nothing (every key on it is new here). Never against the account being left.
    const kept = same ? null : this.deps.store.archivedFile(next.acct)
    const base: DevLogFile = same ? file : kept ?? {
      state: null, recent: [], frozen: null, notifiedUpTo: 0, joinedSeq: 0, preLog: file.preLog ?? [],
      pending: [], announced: [], suspended: [], baselineSeen: true,
    }
    const before = base.state?.active ?? {}
    const added = Object.values(next.active).filter((m) => !before[m.pub])
    const removed = Object.values(before).filter((m) => !next.active[m.pub])
    if (confirm) {
      const parsed = entries.map((e) => parseDevLogEntry(e)).filter((e): e is DevLogEntry => e !== null)
      const selfPub = this.deps.identity().pub
      const signIn = this.deps.signIn()
      const preLog = new Set(base.preLog ?? [])
      const announced = base.announced ?? []
      // Every key the review let in is new here — however the preview and this read differ — unless
      // this machine knew it already or its user unpaired it.
      const news = added.filter((m) => m.pub !== selfPub && !preLog.has(m.pub) && !this.deps.blocked(m.pub))
      const toAnnounce = news.filter((m) => !announced.includes(m.pub))
      // The joined point never moves up past the reviewed head: a shorter list (rolled back, or
      // another account's) must leave every key added to it from here on news.
      const joinedSeq = Math.min(base.joinedSeq ?? base.notifiedUpTo, next.head.seq)
      // The reviewed list is another account's: the departing log follows the same policy as a sign-in
      // (and what a fork suspended in it stays suspended here) — and a kept one of the reviewed account
      // goes on from where it was.
      if (file.state && !same) {
        this.deps.switchAccount?.(file.state.acct, next.acct)
        this.archiveDeparting(file)
      }
      const { joining: _j, ...rest } = base
      const reviewed: DevLogFile = this.carrySuspensions({
        ...rest,
        state: next, recent: parsed.slice(-DEVLOG_RECENT), frozen: null, notifiedUpTo: next.head.seq, joinedSeq,
        firstSeen: this.stamp(base.firstSeen, added, next),
        pending: this.prune([...(base.pending ?? []), ...news.map((m) => m.pub)], next),
        announced: this.prune([...announced, ...toAnnounce.map((m) => m.pub)], next),
        // A review lifts what a fork suspended in this list; a kept list's suspensions were never in
        // the preview, so they stay.
        suspended: same ? [] : this.prune(base.suspended, next),
        looseRemoved: [], reviewedSeq: next.head.seq,
        ...this.withDeparted(base.departed, this.reviewDeparted(base, next, parsed, removed, selfPub, preLog)),
        ...(signIn ? { owner: signIn.epoch } : {}),
      })
      if (!kept || !this.deps.store.restore(next.acct, () => reviewed)) this.deps.store.write(reviewed)
      this.trustState(next, Object.values(next.active))
      for (const m of removed) this.deps.drop(m.pub)
      // The review is done: what a fork suspended is trusted again, along with the rest of the log —
      // after the drops, so a key the reviewed log removed is not pinned again on the way out.
      this.deps.resume?.()
      for (const m of toAnnounce) this.deps.announce(m)
      this.deps.changed?.()
    }
    return { head: next.head, added, removed }
  }

  /** What rides this machine's side of a `group_sync`. */
  gossip(): Record<string, unknown> | undefined {
    const file = this.deps.store.read()
    // Not this sign-in's log yet (it may be the account this machine just left): nothing to say.
    if (!file.state || !this.ownsFile(file)) return undefined
    // The newest hashes let a peer that finds the logs forked say where they split.
    const hashes = file.state.hashes.slice(-GOSSIP_HASHES).map((hash, i, all) => ({ seq: file.state!.head.seq - (all.length - 1 - i), hash }))
    // The account rides along: a device still signed in to the one this machine left must not have its
    // log taken for a fork of this one.
    return { acct: file.state.acct, head: file.state.head, frozen: file.frozen !== null, hashes }
  }

  /**
   * A peer's side of a `group_sync`. Returns what to answer (a responder hands back its own head, and
   * the entries the peer is missing if it is behind).
   */
  heard(peerPub: string, raw: unknown): Record<string, unknown> | undefined {
    const file = this.marks()
    const state = file.state
    // A sign-in waiting for its first read: the file may be the account left behind, and a peer of the
    // new one would freeze it as a fork. Nothing is judged until the log is this sign-in's.
    if (!this.ownsFile(file)) return undefined
    const mine = this.gossip()
    if (!state || !raw || typeof raw !== 'object') return mine
    const p = raw as { acct?: unknown; head?: unknown; frozen?: unknown; tail?: unknown }
    // Another account's log says nothing about this one. A peer from before the account rode along
    // sends none, and is judged as before.
    if (p.acct !== undefined && p.acct !== state.acct) return undefined
    this.frozenPeers.set(peerPub, p.frozen === true)
    const head = p.head as { seq?: unknown; hash?: unknown } | undefined
    if (!head || typeof head.seq !== 'number' || !Number.isSafeInteger(head.seq) || head.seq < 0 || typeof head.hash !== 'string') return mine
    const theirs: DevLogHead = { seq: head.seq, hash: head.hash }
    const relation = compareDevLogHead(state, theirs)
    if (relation === 'fork') { this.freeze('fork'); this.suspendAfterFork(state, raw); return this.gossip() }
    if (relation === 'behind') {
      const tail = Array.isArray(p.tail) ? p.tail.filter((e) => (parseDevLogEntry(e)?.seq ?? 0) > state.head.seq) : []
      // A tail that does not continue this log is a fork; and a log already frozen on one can still
      // learn from this peer's hashes where it split.
      if (file.frozen || (tail.length && !this.accept(tail, false))) this.suspendAfterFork(state, raw)
      // Either way ask the backend too: if it will not serve what a peer already verified, that is a
      // rollback, and the next refresh freezes on it.
      void this.refresh()
      return this.gossip()
    }
    if (relation === 'ahead') {
      const tail = file.recent.filter((e) => e.seq > theirs.seq)
      if (tail.length && tail[0].seq === theirs.seq + 1) return { ...mine, tail }
    }
    return mine
  }

  /**
   * A fork a peer proved with its hashes: the keys added at or after the split — and new here — are
   * not trusted until the list is reviewed (rebaseline). Only locally: nothing is tombstoned or
   * written to the log. Without usable hashes (an older peer, a split outside the window, a rollback)
   * the freeze alone stands.
   */
  private suspendAfterFork(state: DevLogState, theirs: unknown): void {
    const file = this.deps.store.read()
    if (file.frozen?.reason !== 'fork') return
    const split = devLogDivergence(state, theirs)
    if (split === null) return
    const selfPub = this.deps.identity().pub
    const pending = file.pending ?? []
    // Only keys nobody here has marked as seen — and not one a review (`rebaseline --yes`) already let
    // in: another device's old branch must not cost this one the devices its user just looked at.
    const reviewed = file.reviewedSeq ?? -1
    const keys = Object.values(state.active)
      .filter((m) => m.seq >= split && m.pub !== selfPub && pending.includes(m.pub) && m.seq > reviewed)
      .map((m) => m.pub)
    const fresh = keys.filter((k) => !(file.suspended ?? []).includes(k))
    if (!fresh.length) return
    this.deps.store.write({ ...file, suspended: uniq([...(file.suspended ?? []), ...fresh]) })
    this.deps.suspend?.(fresh)
    this.deps.log?.(`[devlog] this computer's and another device's lists split at entry ${split}: not trusting ${fresh.length} key(s) added after it until you review the list (harness devices rebaseline)`)
    this.deps.changed?.()
  }

  /** Keys not trusted here after a fork, until `rebaseline` — and every key a fork suspended in the
   *  kept log of another account, which no other account's log can bring back in. */
  suspendedKeys(): string[] {
    return [...new Set([...(this.deps.store.read().suspended ?? []), ...this.deps.store.archivedSuspended()])]
  }

  /**
   * Mark new devices as seen: the ones in `pubs` (what a window displayed), one (`pub`), every one
   * (nothing named — only the explicit `harness devices dismiss`), and/or the "already on your account"
   * list (`baseline`). Persisted, so it holds across restarts. A key a fork suspended stays flagged
   * when it is only part of a list that was looked at; `pub` — "It's mine" on that very device — is the
   * person vouching for it, and lifts its suspension here (and in every kept account's log). A key that
   * joined and left before anyone looked (`departed`) is cleared the same way: named, or every one.
   *
   * `confirm` — "It's mine", pressed for ONE device (`pub`, or `pubs` naming only it) — also tells the
   * account's other devices, with an acknowledgement this machine signs (deviceAck.ts): they stop showing
   * it as New too. Never for a list that was only looked at, every device at once, or the baseline: only
   * an explicit "It's mine" vouches. Marking it seen here is done before this returns; the promise says
   * whether the other devices were told (false: the backend did not take it, or there was nothing to tell).
   */
  dismiss(opts: { pub?: string; pubs?: string[]; baseline?: boolean; confirm?: boolean } = {}): Promise<boolean> {
    const one = opts.pub ?? (opts.pubs?.length === 1 ? opts.pubs[0] : undefined)
    const wasNew = one !== undefined && (this.marks().pending ?? []).includes(one)
    this.markSeen(opts)
    // Only a key that was new here, and that this machine trusts now: one a fork suspended here (and
    // "It's mine" did not lift) is not this machine's to vouch for.
    if (!opts.confirm || opts.baseline || one === undefined || !wasNew || this.suspendedKeys().includes(one)) return Promise.resolve(false)
    return this.shareAck(one)
  }

  private markSeen(opts: { pub?: string; pubs?: string[]; baseline?: boolean }): void {
    const file = this.marks()
    if (!file.state) return
    const suspended = file.suspended ?? []
    const named = opts.pub !== undefined || opts.pubs !== undefined
    const gone = new Set([...(opts.pubs ?? []), ...(opts.pub !== undefined ? [opts.pub] : [])])
    const keep = (k: string): boolean => (named ? !gone.has(k) : !!opts.baseline) || (suspended.includes(k) && k !== opts.pub)
    const pending = (file.pending ?? []).filter(keep)
    const departed = (file.departed ?? []).filter((d) => (named ? !gone.has(d.pub) : !!opts.baseline))
    const lift = opts.pub !== undefined && suspended.includes(opts.pub)
    // The "already on your account" list was looked at: the first read is over, whatever comes after is
    // news — or a backend that stalls that read could add a key to a list nobody will look at again.
    const { joining: _j, ...rest } = file
    this.deps.store.write({
      ...(opts.baseline ? { ...rest, baselineSeen: true } : file), pending,
      ...(file.departed ? { departed } : {}),
      ...(lift ? { suspended: suspended.filter((k) => k !== opts.pub) } : {}),
    })
    if (lift) {
      this.deps.store.unsuspendArchived([opts.pub!])
      const member = file.state.active[opts.pub!]
      if (member) this.trustState(file.state, [member])
      this.deps.resume?.()
    }
    this.deps.changed?.()
  }

  /** Sign "It's mine" for `pub` and hand it to the backend for the account's other devices. Only from a
   *  log this machine verified, is on, and that is not frozen (a frozen list is not one to vouch from),
   *  about a key on it that is not this machine. Never throws. */
  private async shareAck(pub: string): Promise<boolean> {
    const post = this.deps.postAck
    if (!post) return false
    try {
      const file = this.deps.store.read()
      const state = file.state
      const { pub: selfPub, priv } = this.deps.identity()
      if (!state || file.frozen || !this.ownsFile(file) || pub === selfPub || !state.active[selfPub]) return false
      const member = state.active[pub]
      if (!member) return false
      const ack = signDevAck({ v: DEVACK_VERSION, acct: state.acct, pub, addSeq: member.seq, signer: selfPub, at: this.now() }, priv)
      const kept = await post(ack)
      if (!kept) this.deps.log?.(`[devlog] could not tell your other devices that ${member.label || '(no name)'} (${fp(pub)}) is yours: they still show it as new`)
      return kept
    } catch (err) {
      this.deps.log?.(`[devlog] could not share "It's mine": ${err instanceof Error ? err.message : String(err)}`)
      return false
    }
  }

  /**
   * Every add and remove in the log, newest first, as this machine verified it: the entries come from
   * the backend but each must hash to what this machine already verified, or the log freezes. Offline,
   * what is kept locally (`complete: false`).
   */
  history(): Promise<DeviceLogHistory> {
    // One walk at a time: two interleaved on the same cache would each read the other's entries as a
    // gap in the log and freeze it.
    this.historying ??= this.historyOnce().finally(() => { this.historying = null })
    return this.historying
  }

  private async historyOnce(): Promise<DeviceLogHistory> {
    await this.refresh()
    const file = this.marks()
    const state = file.state
    if (!state) return { rows: [], complete: false, frozen: file.frozen }
    const cache = this.histCache && this.histCache.acct === state.acct ? this.histCache : { acct: state.acct, entries: [] as DevLogEntry[] }
    const last = cache.entries.at(-1)
    if (last && (last.seq > state.head.seq || devLogHash(last) !== state.hashes[last.seq - 1])) cache.entries = []
    this.histCache = cache
    for (let page = 0; page < PAGES && cache.entries.length < state.head.seq; page++) {
      const since = cache.entries.length
      const got = await this.deps.fetch(since)
      if (!got || got.acct !== state.acct) break
      let progressed = false
      for (const raw of got.entries) {
        const e = parseDevLogEntry(raw)
        const rawSeq = (raw as { seq?: unknown } | null)?.seq
        const seq = e?.seq ?? (typeof rawSeq === 'number' ? rawSeq : 0)
        if (seq <= cache.entries.length || seq > state.head.seq) continue
        // At a position this machine verified, anything unreadable or off-hash means the backend is
        // lying about the past: freeze, and show only what was already checked.
        if (!e || e.seq !== cache.entries.length + 1 || devLogHash(e) !== state.hashes[e.seq - 1]) {
          // Only against the log this walk started from: if the file was rebaselined (or moved to
          // another account) while the pages were on their way, the mismatch is with a log that is
          // gone, and says nothing about the backend.
          const now = this.deps.store.read().state
          if (!now || now.acct !== state.acct || now.head.seq !== state.head.seq || now.head.hash !== state.head.hash) {
            this.histCache = null
            return this.historyOf([], false)
          }
          this.freeze('fork')
          return this.historyOf(cache.entries, false)
        }
        cache.entries.push(e)
        progressed = true
      }
      if (!progressed) break
    }
    return this.historyOf(cache.entries, cache.entries.length >= state.head.seq)
  }

  private historyOf(fetched: readonly DevLogEntry[], complete: boolean): DeviceLogHistory {
    const file = this.deps.store.read()
    const state = file.state
    if (!state) return { rows: [], complete: false, frozen: file.frozen }
    // Offline, the newest entries kept locally fill in what could not be fetched.
    const entries = complete ? fetched : [...fetched, ...file.recent.filter((e) => e.seq > (fetched.at(-1)?.seq ?? 0))]
    const rows = devLogHistory(entries, {
      // A key that joined and left before anyone looked is still new, in its rows too.
      selfPub: this.deps.identity().pub, joinedSeq: file.joinedSeq, active: state.active, loose: file.looseRemoved,
      pending: [...(file.pending ?? []), ...(file.departed ?? []).map((d) => d.pub)],
    })
    return { rows, complete, frozen: file.frozen }
  }

  /** The account's devices as this machine's log has them, for the Devices list. */
  list(): DeviceLogListing {
    const file = this.marks()
    const selfPub = this.deps.identity().pub
    const pending = file.pending ?? []
    const suspended = file.suspended ?? []
    const members = Object.values(file.state?.active ?? {})
      .sort((a, b) => a.seq - b.seq)
      .map((m) => {
        const row = { ...m, fingerprint: fp(m.pub), self: m.pub === selfPub, pending: pending.includes(m.pub), suspended: suspended.includes(m.pub) }
        const confirmed = file.confirmed?.[m.pub]
        return confirmed ? { ...row, confirmed } : row
      })
    const labels = new Map(members.map((m) => [m.pub, m.label]))
    const frozenPeers = [...this.frozenPeers].filter(([, frozen]) => frozen).map(([pub]) => labels.get(pub) ?? fp(pub))
    // Each row carries when this machine first applied it (never the entry's self-chosen `at`).
    const withSeen = members.map((m) => (file.firstSeen?.[m.pub] === undefined ? m : { ...m, firstSeen: file.firstSeen[m.pub] }))
    const joinedSeq = file.joinedSeq ?? 0
    const preLog = new Set(file.preLog ?? [])
    const baseline = withSeen.filter((m) => !m.self && (m.seq <= joinedSeq || preLog.has(m.pub))).map((m) => m.pub)
    const holder = file.conflict
    const conflict = holder && file.state?.active[holder.pub] && !file.state.active[selfPub] ? holder : null
    return {
      head: file.state?.head ?? null, frozen: file.frozen, self: selfPub, members: withSeen, frozenPeers,
      pending, suspended, joinedSeq, baseline, baselineSeen: file.baselineSeen ?? true, conflict, departed: file.departed ?? [],
      ...(this.registerError ? { registerError: this.registerError } : {}),
    }
  }
}