heyquilt 0.0.1 → 0.3.106

package/src/pathrules.js

@@ -0,0 +1,134 @@
+// Which paths are synced, and which are safe to accept from a peer. No Node
+// APIs here: the web app uses the same rules as the CLI.
+import ignore from 'ignore'
+
+export const MAX_TEXT_BYTES = 2 * 1024 * 1024
+export const MAX_BINARY_BYTES = 8 * 1024 * 1024
+// Binary files this big or bigger are stored encrypted outside the session document.
+export const LARGE_FILE_BYTES = 256 * 1024
+// The most a stored file may be (the relay may allow less).
+export const MAX_STORED_BINARY_BYTES = 100 * 1024 * 1024
+
+/**
+ * Where each person's app saves the files sent in the session's chat (session.js): only those
+ * who can see the message get the file, so the folder is never synced, committed or pushed.
+ */
+export const CHAT_FILES = 'Chat files'
+
+// Never synced, regardless of .gitignore. .env files are excluded so secrets
+// stay on each person's machine; Claude Code worktrees are whole private
+// copies of the project.
+export const ALWAYS_IGNORED = [
+  '.git', '.quilt', '.cowove', 'node_modules', '.DS_Store', 'Thumbs.db', '.claude/worktrees',
+  `/${CHAT_FILES}`,
+  // Each person's own Claude Code settings (permissions, Quilt's hooks) stay on their machine.
+  '.claude/settings.local.json',
+  // Build output and caches: large, machine-specific, and rebuilt by each person.
+  '.next', '.turbo', '.nuxt', '.svelte-kit', '.parcel-cache', '.vercel',
+  '.env', '.env.*', '!.env.example',
+  // A .quiltignore is each person's own list of what stays on their machine, so it stays there too.
+  '.quiltignore', '.cowoveignore',
+  '*.swp', '*.swo', '*~', '.#*'
+]
+
+/** Files whose patterns say what isn't synced, in the folder they sit in. */
+export const IGNORE_FILES = ['.gitignore', '.quiltignore', '.cowoveignore']
+
+/**
+ * Rewrites an ignore file found in subfolder `dir` so its patterns apply from
+ * the project root, the way git scopes a nested .gitignore to its folder.
+ */
+export function scopeIgnore (text, dir) {
+  if (!dir) return text
+  return text.split(/\r?\n/).map((line) => {
+    if (!line.trim() || line.startsWith('#')) return line
+    const neg = line.startsWith('!')
+    const body = neg ? line.slice(1) : line
+    // A slash anywhere but the end anchors the pattern to this folder.
+    const anchored = body.replace(/\/+\s*$/, '').includes('/')
+    const scoped = anchored ? `${dir}/${body.replace(/^\//, '')}` : `${dir}/**/${body}`
+    return (neg ? '!' : '') + scoped
+  }).join('\n')
+}
+
+/**
+ * An ignore matcher from the built-ins plus the text of .gitignore / .quiltignore
+ * files. The built-ins are kept apart from the project patterns, so a shared
+ * .gitignore saying "!.env" can't make anyone's secrets sync.
+ */
+export function makeIgnore (texts = []) {
+  const builtin = ignore().add(ALWAYS_IGNORED)
+  const project = ignore()
+  for (const t of texts) if (t) project.add(t)
+  return {
+    add (text) { project.add(text); return this },
+    ignores (p) { return builtin.ignores(p) || project.ignores(p) }
+  }
+}
+
+export function isIgnored (ig, rel) {
+  if (!rel || rel === '.') return false
+  // Check every ancestor directory so "dist/" also excludes "dist/a/b.js".
+  const parts = rel.split('/')
+  for (let i = 1; i <= parts.length; i++) {
+    const sub = parts.slice(0, i).join('/')
+    if (ig.ignores(sub)) return true
+    if (i < parts.length && ig.ignores(sub + '/')) return true
+  }
+  return false
+}
+
+// Names Windows reserves for devices, with any extension: a member there could never write them.
+const WINDOWS_DEVICE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i
+const utf8Length = (s) => new TextEncoder().encode(s).length
+
+/**
+ * Validates a path received from a peer. Rejects anything that could escape
+ * the project folder or touch git internals, and names that some member's
+ * disk could not hold (a change nobody can write is a change nobody should
+ * share).
+ */
+export function isSafeRelPath (rel) {
+  if (typeof rel !== 'string' || !rel || rel.length > 1024) return false
+  if (rel.includes('\\') || rel.includes('\0')) return false
+  if (rel.startsWith('/') || /^[A-Za-z]:/.test(rel)) return false
+  const parts = rel.split('/')
+  for (const part of parts) {
+    if (part === '' || part === '.' || part === '..') return false
+    if (WINDOWS_DEVICE.test(part) || part.endsWith('.') || part.endsWith(' ')) return false
+    if (part.length > 255 || utf8Length(part) > 255) return false
+  }
+  const first = parts[0].toLowerCase()
+  if (first === '.git' || first === '.quilt' || first === '.cowove') return false
+  return true
+}
+
+/** Whether two claim patterns can cover the same file (paths: files that exist now). */
+export function patternsOverlap (a, b, paths = []) {
+  if (a === b) return true
+  const ma = globMatcher(a)
+  const mb = globMatcher(b)
+  return ma(b) || mb(a) || paths.some((p) => ma(p) && mb(p))
+}
+
+/** Converts a simple glob (*, **, ?) or a plain path/folder into a matcher. */
+export function globMatcher (pattern) {
+  let p = pattern.trim().replace(/^\.\//, '')
+  if (!/[*?]/.test(p)) {
+    const base = p.replace(/\/+$/, '')
+    return (rel) => rel === base || rel.startsWith(base + '/')
+  }
+  let re = ''
+  for (let i = 0; i < p.length; i++) {
+    const c = p[i]
+    if (c === '*' && p[i + 1] === '*') {
+      re += '.*'
+      i++
+      if (p[i + 1] === '/') i++
+    } else if (c === '*') re += '[^/]*'
+    else if (c === '?') re += '[^/]'
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  const rx = new RegExp(`^${re}$`)
+  return (rel) => rx.test(rel)
+}

package/src/persona.js

@@ -0,0 +1,101 @@
+// AI sessions as their own members. Several AI sessions often work through one person's
+// app at once (Claude Code in one window, Cursor in another, two Claude Code chats). Each
+// gets a name of its own, after what it works on, so partners can tell them apart, message
+// the right one, and see whose claims are whose: "Daniel · file-queue", "Daniel · hosted costs".
+//
+// The name is the person's first name and a label. The label comes from the session's git
+// branch when it works on one (a branch names the work and doesn't change), otherwise from
+// the first thing it says it is doing (its focus, what it shares, the task it takes), and
+// the agent can rename itself. Until then it is named after its tool.
+import { execFileSync } from 'node:child_process'
+
+export const PERSONA_SEP = ' · '
+const MAX_LABEL = 32
+
+/** The person's first name: "Daniel Carmichael" -> "Daniel". */
+export const firstName = (person) => String(person || '').trim().split(/\s+/)[0] || 'AI'
+
+/**
+ * A label as it may appear in a name: one line, no separator or @, at most 32 characters
+ * (cut at a word). '' when nothing is left.
+ */
+export function cleanLabel (label) {
+  let s = String(label || '').replace(/[\r\n\t]+/g, ' ').replace(/[@·]/g, ' ').replace(/[`"'<>]/g, '').replace(/\s+/g, ' ').trim()
+  if (s.length > MAX_LABEL) {
+    const cut = s.slice(0, MAX_LABEL + 1)
+    s = (cut.lastIndexOf(' ') > 8 ? cut.slice(0, cut.lastIndexOf(' ')) : cut.slice(0, MAX_LABEL)).trim()
+  }
+  return s.replace(/[\s.,;:!?-]+$/, '')
+}
+
+/** "Daniel · file-queue". */
+export const personaName = (person, label) => `${firstName(person)}${PERSONA_SEP}${cleanLabel(label) || 'AI'}`
+
+const PLAIN_BRANCHES = new Set(['main', 'master', 'trunk', 'develop', 'dev', 'head', ''])
+
+/**
+ * A label from a git branch, or '' for one that says nothing about the work (main, master,
+ * a detached HEAD). Tool prefixes ("claude/", "cursor/", "feature/") are dropped.
+ */
+export function labelFromBranch (branch) {
+  const b = String(branch || '').trim()
+  if (PLAIN_BRANCHES.has(b.toLowerCase())) return ''
+  const last = b.split('/').filter(Boolean).pop() || ''
+  return cleanLabel(last)
+}
+
+/** The git branch checked out in `dir`, or '' (not a repository, or git missing). */
+export function gitBranch (dir) {
+  try {
+    // symbolic-ref also answers on a branch with no commits yet; a detached HEAD has no branch.
+    return execFileSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: dir, stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).toString().trim()
+  } catch { return '' }
+}
+
+const FILLER = new Set(['i', 'im', 'i\'m', 'am', 'is', 'are', 'was', 'the', 'a', 'an', 'to', 'for', 'on', 'of', 'and', 'or', 'my', 'our', 'me', 'now', 'just', 'currently', 'working', 'work', 'going', 'will', 'be', 'about', 'with', 'in', 'this', 'that', 'these', 'it', 'its', 'please', 'can', 'could', 'would', 'should', 'you', 'your', 'we', 'let', 'lets', 'let\'s', 'start', 'starting', 'why', 'what', 'how', 'when', 'where', 'there', 'some', 'so', 'do', 'does', 'did', 'have', 'has', 'hey', 'hi', 'ok', 'okay', 'yes', 'no', 'all', 'also', 'into', 'at', 'from', 'by', 'up', 'out', 'make', 'sure', 'want', 'need', 'like', 'use', 'using', 'thanks', 'thank', 'their', 'his', 'her', 'them', 'they', 'he', 'she', 'if', 'then', 'but', 'than', 'which', 'who', 'while', 'very', 'really', 'something', 'anything', 'everything', 'thing', 'things'])
+
+// An opener that tells what happened before the ask, not what the session does ("I just had gpt
+// add some info and double check your plan", "we tried the fix and it broke"): the label comes
+// from the first clause after it.
+const NARRATION = new Set(['had', 'have', 'has', 'was', 'were', 'did', 'got', 'asked', 'told', 'made', 'tried', 'ran', 'saw', 'noticed', 'found', 'used', 'wanted', 'went', 'gave', 'sent', 'said', 'says', 'thought', 'think', 'thinking', 'added', 'wrote', 'changed', 'pulled', 'pushed', 'deployed', 'merged', 'been', 'being', 'already', 'earlier', 'yesterday', 'before', 'previously', 'since', 'remember'])
+// Another AI or tool the opener names ("had gpt add", "asked claude to"): not this session's work.
+const TOOL_NAMES = /^(?:(?:chat)?gpt[-\w.]*|claude|codex|cursor|gemini|grok|copilot|openai|anthropic|ai|bot|agent|assistant|llm|model|o[1-9](?:-\w+)?)$/i
+// Where one clause ends and the next begins.
+const CLAUSE = /[.!?;:\n]+|,\s+|\s+(?:and|then|but|so|now)\s+/i
+
+/** The words of `text` that carry meaning, in order, lower case. */
+function meaningfulWords (text) {
+  return String(text || '').split(/\s+/).filter((w) => w && !/^(https?:|\/|~|<)/.test(w))
+    .map((w) => w.replace(/[^\p{L}\p{N}'-]/gu, '').replace(/^['-]+|['-]+$/g, '')).filter(Boolean)
+    .filter((w) => !FILLER.has(w.toLowerCase()) && w.length <= 24).map((w) => w.toLowerCase())
+}
+
+/**
+ * A label from what a session says it is doing (or was asked): its first few words that carry
+ * meaning, after any opener about what happened before ("I just had gpt add some info and
+ * double check your plan" -> "double check plan").
+ */
+export function labelFromText (text) {
+  const clauses = String(text || '').split(CLAUSE).map((c) => c.trim()).filter(Boolean)
+  const words = clauses.map(meaningfulWords)
+  let from = words.findIndex((w) => w.length && !NARRATION.has(w[0]))
+  let first
+  if (from >= 0) first = words[from]
+  else {
+    // Only narration: what was done, without the opener and the tool it names.
+    from = words.findIndex((w) => w.length)
+    if (from < 0) return ''
+    first = words[from].slice(1)
+    if (first.length && TOOL_NAMES.test(first[0])) first = first.slice(1)
+  }
+  return cleanLabel([...first, ...words.slice(from + 1).flat()].slice(0, 3).join(' '))
+}
+
+/** A label from the first file a session edits: its name without the extension ("session.js" -> "session"). */
+export function labelFromFile (rel) {
+  const base = String(rel || '').split('/').filter(Boolean).pop() || ''
+  return cleanLabel(base.replace(/\.[A-Za-z0-9]+$/, ''))
+}
+
+// "Daniel's AI": all of a person's AI sessions as one name (pure, shared with the app).
+export { AI_SUFFIX, aiName, foldPersonas } from './ui/chat.js'

package/src/presence.js

@@ -0,0 +1,360 @@
+// Presence reports: the relay tells the accounts API who is in which session, and
+// when, so people's dashboards can show their sessions and who they worked with.
+// Only for connections with a pass (an account), and only when the relay has both
+// QUILT_API_URL and RELAY_API_SECRET. Events wait in a queue that is kept on disk
+// (`<dataDir>/presence-queue.jsonl`), so a restart or a down API loses nothing, and
+// are sent every minute, at most 500 per request, in order.
+//
+// For the audit trail, a visit says how the member came in (`via`: the app or a hosted
+// agent, and its `tool`), why it ended (`reason`, see END_REASONS), and what it did
+// meanwhile (`act` events: an action and its target, a path or a task id; never file
+// contents or chat text). The same action on the same target is reported at most once
+// a minute per visit.
+import fs from 'node:fs'
+import crypto from 'node:crypto'
+
+export const PRESENCE_FILE = 'presence-queue.jsonl'
+export const PRESENCE_FLUSH_MS = 60 * 1000
+export const PRESENCE_BATCH = 500
+export const PRESENCE_MAX_QUEUE = 100_000
+export const PRESENCE_MAX_BACKOFF_MS = 10 * 60 * 1000
+// A full rewrite of the queue file is O(queue size): worth doing right after load() or
+// close(), but not on every drop or send while the relay is under load.
+export const PRESENCE_REWRITE_MS = 60 * 1000
+const SYNC_MS = 1000
+export const ACT_COALESCE_MS = 60 * 1000
+/** Why a visit ended. The accounts API turns an agent's `pass_expired` or `idle` into `revoked` when its keys were revoked first. */
+export const END_REASONS = ['left', 'disconnected', 'removed', 'pass_expired', 'session_ended', 'relay_restart', 'idle', 'replaced', 'needs_update']
+export const ACTIONS = ['created', 'edited', 'deleted', 'claimed', 'released', 'requested', 'handed_off', 'withdrew', 'messaged', 'task', 'tool']
+const MAX_TARGET = 300
+const SEND_TIMEOUT_MS = 15 * 1000
+const CLOSE_TIMEOUT_MS = 5 * 1000
+
+export class PresenceReporter {
+  /**
+   * @param {object} o
+   * @param {string} o.apiUrl   the accounts API, e.g. https://api.heyquilt.com
+   * @param {string} o.secret   RELAY_API_SECRET. Never logged.
+   * @param {string|null} [o.file]  the queue file; null keeps the queue in memory only
+   */
+  constructor ({ apiUrl, secret, file = null, log = () => {}, now = Date.now, fetch = globalThis.fetch, flushMs = PRESENCE_FLUSH_MS, batch = PRESENCE_BATCH, maxQueue = PRESENCE_MAX_QUEUE, maxBackoffMs = PRESENCE_MAX_BACKOFF_MS, syncMs = SYNC_MS, timeoutMs = SEND_TIMEOUT_MS, rewriteMs = PRESENCE_REWRITE_MS, closeTimeoutMs = CLOSE_TIMEOUT_MS }) {
+    this.url = `${String(apiUrl).replace(/\/+$/, '')}/v1/relay/presence`
+    this.secret = secret
+    this.file = file
+    this.log = log
+    this.now = now
+    this.fetch = fetch
+    this.flushMs = flushMs
+    this.batch = batch
+    this.maxQueue = maxQueue
+    this.maxBackoffMs = maxBackoffMs
+    this.syncMs = syncMs
+    this.timeoutMs = timeoutMs
+    this.rewriteMs = rewriteMs
+    this.closeTimeoutMs = closeTimeoutMs
+    this.queue = [] // { seq, ev, startSeq? }, oldest first; an `end` notes its `start`'s seq (0: sent by an earlier run)
+    this.seq = 0
+    this.sentSeq = 0 // the highest seq the accounts API has taken
+    this.inFlight = 0 // the highest seq in the request being sent; 0 when nothing is
+    this.open = new Map() // start event id -> { start, room, account }: visits not ended yet
+    this.startSeqs = new Map() // start event id -> its seq, for visits not ended yet
+    this.unwritten = [] // queue lines not yet appended to the file
+    this.rewrite = false // the file no longer matches the queue: write it whole next time
+    this.lastRewriteAt = -Infinity // so the first rewrite (from load(), or the first drop) is never throttled
+    this.urgent = false // a rewrite a successful send is waiting on: never throttled
+    this.full = false // logged once per overflow episode; cleared once the queue drains below the cap
+    this.saveFailing = false // logged once per failure episode; cleared by the next save that works
+    this.failures = 0
+    this.retryAt = 0
+    this.sending = null
+    this.closed = false
+    this.timers = []
+    this.acted = new Map() // start event id -> Map(action|target -> when last reported), for visits not ended yet
+  }
+
+  /**
+   * Reads the queue file a previous run left, and ends at "now" every visit it had
+   * started and not ended (the relay crashed, or was redeployed). Returns how many.
+   */
+  load () {
+    if (!this.file) return 0
+    let text = ''
+    try { text = fs.readFileSync(this.file, 'utf8') } catch (err) { if (err.code !== 'ENOENT') this.log(`presence: could not read ${this.file}: ${err.message}`); return 0 }
+    let bad = 0
+    const seqs = new Map() // start event id -> seq, for the starts in the file
+    const lastName = new Map() // room -> seq of its newest name in the file
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue
+      let row
+      try { row = JSON.parse(line) } catch { bad++; continue } // a line cut off by a crash
+      // JSON.parse accepts bare null/numbers/strings too: never trust the shape before checking it.
+      if (!row || typeof row !== 'object') { bad++; continue }
+      if (Array.isArray(row.open)) {
+        for (const v of row.open) if (v && v.start) this.open.set(v.start, v)
+        continue
+      }
+      if (!row.id || !row.type) { bad++; continue }
+      const seq = ++this.seq
+      if (row.type === 'start') {
+        this.open.set(row.id, { start: row.id, room: row.room, account: row.account })
+        seqs.set(row.id, seq)
+      }
+      if (row.type === 'end') this.open.delete(row.start)
+      if (row.type === 'name') lastName.set(row.room, seq)
+      // A start this file doesn't hold was sent by an earlier run: 0 marks that.
+      this.queue.push(row.type === 'end' ? { seq, ev: row, startSeq: seqs.get(row.start) || 0 } : { seq, ev: row })
+    }
+    // A room's older names (from saves between the queue's rewrites) would only be overwritten.
+    this.queue = this.queue.filter((x) => x.ev.type !== 'name' || lastName.get(x.ev.room) === x.seq)
+    for (const id of this.open.keys()) if (seqs.has(id)) this.startSeqs.set(id, seqs.get(id))
+    if (bad) this.log(`presence: skipped ${bad} unreadable line(s) in ${this.file}`)
+    const ended = this.open.size
+    this.endAll('relay_restart')
+    this.rewrite = true
+    this.persist(true) // startup: write the cleaned-up state now, not whenever the throttle allows
+    return ended
+  }
+
+  /** Sends every minute (sooner retries wait for their backoff) and saves the queue every second. */
+  start () {
+    const tick = setInterval(() => { this.tick().catch(() => {}) }, this.flushMs)
+    const sync = setInterval(() => this.persist(), this.syncMs)
+    tick.unref()
+    sync.unref()
+    this.timers.push(tick, sync)
+  }
+
+  get size () { return this.queue.length }
+
+  /** Someone with a pass was let into a room. Returns the visit, for visitEnd. */
+  visitStart ({ room, account, name, owner = false, via = '', tool = '' }) {
+    if (this.closed) return null
+    const ev = { id: crypto.randomUUID(), type: 'start', room, account, name, ...(owner ? { owner: true } : {}), ...(via ? { via } : {}), ...(tool ? { tool: String(tool).slice(0, 40) } : {}), at: this.now() }
+    const visit = { start: ev.id, room, account }
+    this.open.set(ev.id, visit)
+    this.startSeqs.set(ev.id, this.enqueue(ev))
+    return visit
+  }
+
+  /** That connection left (closed, removed, ended, or its pass lapsed), for `reason`; `at` defaults to now. Once per visit. */
+  visitEnd (visit, reason = 'left', at) {
+    if (this.closed || !visit || !this.open.delete(visit.start)) return
+    this.enqueueEnd(visit, reason, at)
+  }
+
+  /**
+   * Someone in a visit did something: `action` (one of ACTIONS) on `target` (a path, a
+   * task id or a tool name). Repeats of the same action on the same target within a
+   * minute are not reported again.
+   */
+  act (visit, action, target = '') {
+    if (this.closed || !visit || !this.open.has(visit.start) || !ACTIONS.includes(action)) return
+    const t = String(target || '').slice(0, MAX_TARGET)
+    const at = this.now()
+    let seen = this.acted.get(visit.start)
+    if (!seen) this.acted.set(visit.start, (seen = new Map()))
+    const k = `${action}|${t}`
+    if (at - (seen.get(k) ?? -Infinity) < ACT_COALESCE_MS) return
+    seen.set(k, at)
+    if (seen.size > 1000) for (const [key, when] of seen) if (at - when >= ACT_COALESCE_MS) seen.delete(key)
+    this.enqueue({ id: crypto.randomUUID(), type: 'act', start: visit.start, room: visit.room, account: visit.account, action, ...(t ? { target: t } : {}), at })
+  }
+
+  /**
+   * The owner named the session. Only the newest name matters, so a room keeps at most
+   * one waiting: a rename replaces the one queued before it (unless that one is already
+   * on its way to the API), and renames can never pile up in the queue.
+   */
+  rename ({ room, name }) {
+    if (this.closed) return
+    const i = this.queue.findIndex((x) => x.ev.type === 'name' && x.ev.room === room && x.seq > this.inFlight)
+    if (i >= 0) {
+      this.queue.splice(i, 1)
+      this.rewrite = true // the replaced line is still in the file
+    }
+    this.enqueue({ id: crypto.randomUUID(), type: 'name', room, name, at: this.now() })
+  }
+
+  /** Ends every open visit now: on shutdown, and for visits a previous run left open. */
+  endAll (reason = 'relay_restart') {
+    for (const visit of [...this.open.values()]) {
+      this.open.delete(visit.start)
+      this.enqueueEnd(visit, reason)
+    }
+  }
+
+  enqueueEnd (visit, reason, at) {
+    const startSeq = this.startSeqs.get(visit.start) || 0
+    this.startSeqs.delete(visit.start)
+    this.acted.delete(visit.start)
+    const when = Number.isFinite(at) ? Math.min(at, this.now()) : this.now()
+    this.enqueue({ id: crypto.randomUUID(), type: 'end', start: visit.start, room: visit.room, account: visit.account, ...(END_REASONS.includes(reason) ? { reason } : {}), at: when }, startSeq)
+  }
+
+  /** Returns the event's seq. */
+  enqueue (ev, startSeq) {
+    const seq = ++this.seq
+    this.queue.push(startSeq === undefined ? { seq, ev } : { seq, ev, startSeq })
+    this.unwritten.push(ev)
+    if (this.queue.length > this.maxQueue) this.dropOldest()
+    return seq
+  }
+
+  /**
+   * Drops the oldest tenth of the cap in one go, not one event at a time: at one per
+   * event, a relay that's constantly over the cap would rewrite the whole queue file
+   * and log a line on every single enqueue. Prefers dropping the oldest `start`
+   * together with its matching `end` (if that `end` is already queued too): the pair
+   * is a visit that's over and done with, the least useful thing to still be holding.
+   * A `name` is never dropped: renames are rare, and since the `name` op is now
+   * idempotent (a repeat is never re-queued), a dropped one is gone for good. If every
+   * `start` has already been paired off or dropped and more still needs to go, the
+   * oldest unmatched `end`s go next (an `end` whose `start` was dropped is harmless: the
+   * accounts API ignores it). Never dropped: anything in the request being sent (it
+   * reaches the API anyway), and an `end` whose `start` was sent or is being sent (the
+   * visit would stay open on the dashboard forever). One `filter` pass over the queue,
+   * never a per-element shift: a drop must stay cheap even at ~100,000 events.
+   */
+  dropOldest () {
+    const sent = Math.max(this.sentSeq, this.inFlight)
+    const drop = Math.max(this.queue.length - this.maxQueue, Math.ceil(this.maxQueue / 10))
+    const endIndexByStart = new Map() // start event id -> index of its `end`, if queued
+    this.queue.forEach((x, i) => { if (x.ev.type === 'end') endIndexByStart.set(x.ev.start, i) })
+    const remove = new Set()
+    let dropped = 0
+    // What visits did is the most plentiful and the least load-bearing: the oldest of it goes first.
+    for (let i = 0; i < this.queue.length && dropped < drop; i++) {
+      const x = this.queue[i]
+      if (x.ev.type === 'act' && x.seq > this.inFlight) { remove.add(i); dropped++ }
+    }
+    for (let i = 0; i < this.queue.length && dropped < drop; i++) {
+      const x = this.queue[i]
+      if (x.ev.type !== 'start' || x.seq <= this.inFlight || remove.has(i)) continue
+      remove.add(i); dropped++
+      const endIndex = endIndexByStart.get(x.ev.id)
+      if (endIndex !== undefined && !remove.has(endIndex)) { remove.add(endIndex); dropped++ }
+    }
+    // Nothing left to pair off a `start` with: the oldest leftover `end`s are next.
+    for (let i = 0; i < this.queue.length && dropped < drop; i++) {
+      const x = this.queue[i]
+      if (x.ev.type === 'end' && x.seq > this.inFlight && x.startSeq > sent && !remove.has(i)) { remove.add(i); dropped++ }
+    }
+    if (remove.size) this.queue = this.queue.filter((_, i) => !remove.has(i))
+    this.rewrite = true
+    if (!this.full) {
+      this.full = true
+      this.log(`presence: the queue is full (${this.maxQueue} events); dropped ${dropped} oldest event(s)`)
+    }
+  }
+
+  /** Once the queue has drained back under the cap, the next overflow logs again. */
+  checkDrained () {
+    if (this.full && this.queue.length < this.maxQueue) this.full = false
+  }
+
+  /**
+   * Saves what's new in the queue: appended and fsynced, or the whole file when it has
+   * to be (dropped or sent events leave the file out of sync with the queue, since
+   * appending can only add lines, never remove them). A whole-file rewrite is O(queue
+   * size): a drop's rewrite can wait up to `rewriteMs` (events keep being appended
+   * meanwhile, so nothing is lost), but one a successful send asked for (`urgent`) never
+   * waits, or a restart could re-read and re-send events the accounts API already has.
+   */
+  persist (force = false) {
+    if (!this.file) return
+    const rewriteNow = this.rewrite && (force || this.urgent || this.now() - this.lastRewriteAt >= this.rewriteMs)
+    if (!rewriteNow && !this.unwritten.length) return
+    try {
+      if (rewriteNow) {
+        // Written whole, then renamed: a crash mid-write leaves the old file, never half of one.
+        const tmp = `${this.file}.tmp`
+        const lines = [JSON.stringify({ open: [...this.open.values()] }), ...this.queue.map((x) => JSON.stringify(x.ev))]
+        const fd = fs.openSync(tmp, 'w')
+        try { fs.writeSync(fd, lines.join('\n') + '\n'); fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+        fs.renameSync(tmp, this.file)
+        this.rewrite = false
+        this.urgent = false
+        this.lastRewriteAt = this.now()
+        this.unwritten = [] // the rewrite above already includes every queued event
+      } else if (this.unwritten.length) {
+        const fd = fs.openSync(this.file, 'a')
+        try { fs.writeSync(fd, this.unwritten.map((ev) => JSON.stringify(ev)).join('\n') + '\n'); fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+        this.unwritten = []
+      }
+      this.saveFailing = false
+    } catch (err) {
+      // An append that failed may have left part of a line: the next save that works
+      // writes the whole file, which has every queued event, so nothing waits to be appended.
+      this.rewrite = true
+      this.unwritten = []
+      if (!this.saveFailing) this.log(`presence: could not save the queue: ${err.message}`)
+      this.saveFailing = true
+    }
+  }
+
+  /** Sends now unless a failure's backoff hasn't run out. */
+  async tick () {
+    if (this.now() < this.retryAt) return false
+    return this.flush()
+  }
+
+  /**
+   * Sends everything queued, oldest first, in requests of at most 500. Resolves true
+   * when the queue is empty, false after a failure (the events stay for the retry).
+   */
+  flush () {
+    if (!this.sending) this.sending = this.send().finally(() => { this.sending = null })
+    return this.sending
+  }
+
+  async send () {
+    let sent = false
+    try {
+      while (this.queue.length) {
+        const chunk = this.queue.slice(0, this.batch)
+        this.inFlight = chunk[chunk.length - 1].seq
+        const res = await this.fetch(this.url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', authorization: `Bearer ${this.secret}` },
+          body: JSON.stringify({ events: chunk.map((x) => x.ev) }),
+          signal: AbortSignal.timeout(this.timeoutMs)
+        })
+        if (!res.ok) throw new Error(`the accounts API answered ${res.status}`)
+        // By sequence number: the queue may have dropped its oldest while this was in flight.
+        const last = this.inFlight
+        this.sentSeq = last
+        this.inFlight = 0
+        const i = this.queue.findIndex((x) => x.seq > last)
+        this.queue = i < 0 ? [] : this.queue.slice(i)
+        this.checkDrained()
+        sent = true
+      }
+      this.failures = 0
+      this.retryAt = 0
+      return true
+    } catch (err) {
+      this.failures++
+      const wait = Math.min(this.flushMs * 2 ** (this.failures - 1), this.maxBackoffMs)
+      this.retryAt = this.now() + wait
+      this.log(`presence: could not report to the accounts API (${err.cause?.code || err.message}); trying again in ${Math.round(wait / 1000)} s`)
+      return false
+    } finally {
+      this.inFlight = 0
+      if (sent) { this.rewrite = true; this.urgent = true; this.persist() }
+    }
+  }
+
+  /** On shutdown: ends every open visit, stops the timers, saves the queue, and tries one last send (bounded by closeTimeoutMs). */
+  async close () {
+    if (this.closed) return
+    for (const t of this.timers) clearInterval(t)
+    this.timers = []
+    this.endAll('relay_restart')
+    this.persist(true)
+    this.closed = true
+    let timer
+    await Promise.race([this.flush(), new Promise((resolve) => { timer = setTimeout(resolve, this.closeTimeoutMs) })])
+    clearTimeout(timer)
+    this.persist(true)
+  }
+}

package/src/private-file.js

@@ -0,0 +1,41 @@
+// Files only you should read (this computer's sign-in, agents' keys): written
+// atomically with mode 0600, and never through a symlink.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+/** True if `file` is a symlink (a missing file isn't). */
+export function isSymlink (file) {
+  try {
+    return fs.lstatSync(file).isSymbolicLink()
+  } catch (err) {
+    if (err.code === 'ENOENT') return false
+    throw err
+  }
+}
+
+/**
+ * Writes JSON to `file`: a private temp file in the same folder, fsynced, then
+ * renamed over the target. The rename replaces whatever is there without
+ * following it, and a half-written file is never seen at the real path.
+ */
+export function writePrivateJson (file, data) {
+  if (isSymlink(file)) throw new Error(`Refusing to write ${file}: it's a symlink`)
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`)
+  const fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600)
+  try {
+    fs.writeSync(fd, JSON.stringify(data, null, 2))
+    fs.fsyncSync(fd)
+  } catch (err) {
+    fs.closeSync(fd)
+    try { fs.unlinkSync(tmp) } catch {}
+    throw err
+  }
+  fs.closeSync(fd)
+  try {
+    fs.renameSync(tmp, file)
+  } catch (err) {
+    try { fs.unlinkSync(tmp) } catch {}
+    throw err
+  }
+}