k0-board 0.4.0 → 0.6.0

package/server/prices.js

@@ -0,0 +1,59 @@
+/**
+ * What a request would have cost at the public API price list.
+ *
+ * With a subscription nobody pays per message, so this is not a bill: it is the one yardstick that
+ * puts a Fable hour and a Haiku hour on the same scale. The Usage page says so wherever it shows a
+ * dollar sign.
+ *
+ * Anthropic's first-party rates, dollars per million tokens, as published on 2026-06-24. Cache
+ * writes are 1.25× input for the five-minute lifetime and 2× for the hour; cache reads 0.1× input,
+ * except on Fable 5.1, whose reads are a flat $0.25. Fast mode on Opus 5 is $10/$50, twice the
+ * standard rate, and the multiplier is applied to the whole request.
+ *
+ * A model that is not in this table costs `null`, never zero: a page that added up an unknown
+ * model as free would be telling you the wrong thing with complete confidence.
+ */
+export const LIST_DATE = '2026-06-24'
+
+const RATES = {
+  'claude-fable-5-1': { input: 10, output: 50, read: 0.25 },
+  'claude-fable-5': { input: 10, output: 50, read: 1 },
+  'claude-mythos-5-1': { input: 10, output: 50, read: 0.25 },
+  'claude-mythos-5': { input: 10, output: 50, read: 1 },
+  'claude-opus-5': { input: 5, output: 25, fast: 2 },
+  'claude-opus-4-8': { input: 5, output: 25, fast: 2 },
+  'claude-opus-4-7': { input: 5, output: 25 },
+  'claude-opus-4-6': { input: 5, output: 25 },
+  'claude-sonnet-5': { input: 2, output: 10 },
+  'claude-sonnet-4-6': { input: 3, output: 15 },
+  'claude-haiku-4-5': { input: 1, output: 5 },
+}
+
+/** `claude-haiku-4-5-20251001` is `claude-haiku-4-5`: the snapshot date changes nothing here. */
+export function modelId(raw) {
+  const m = String(raw || '').trim()
+  return m.replace(/-\d{8}$/, '')
+}
+
+export const known = (model) => Object.hasOwn(RATES, modelId(model))
+
+/**
+ * Dollars for one request's `usage`, or null for a model not on the list.
+ *
+ * `tokens` is the shape k0 keeps, not the API's: `input`, `output`, `cacheRead`, `write5m`,
+ * `write1h`. Thinking tokens are already inside `output` — the API bills them as output — so they
+ * are not added a second time.
+ */
+export function cost(model, tokens, speed = 'standard') {
+  const r = RATES[modelId(model)]
+  if (!r) return null
+  const read = r.read ?? r.input * 0.1
+  const perMillion =
+    (tokens.input || 0) * r.input +
+    (tokens.output || 0) * r.output +
+    (tokens.cacheRead || 0) * read +
+    (tokens.write5m || 0) * r.input * 1.25 +
+    (tokens.write1h || 0) * r.input * 2
+  const fast = speed === 'fast' ? r.fast ?? 1 : 1
+  return (perMillion * fast) / 1e6
+}

package/server/projects.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { projectRecency } from './db.js'
+import { projectRecency, listStories } from './db.js'
 import { hasDocs } from './files.js'
 import { shell } from '../platform/index.js'
 
@@ -94,13 +94,36 @@ function scan(fromClaude) {
 
 /**
  * The repositories, most used at the top. Recency is the fresher of two histories: Claude
- * Code's, which knows where you have worked even outside k0, and k0's own cards, which are the
+ * Code's, which knows where you have worked even outside k0, and k0's own stories, which are the
  * only thing that notices a session still open right now.
  */
+// How long a reading of the home directory is worth. The list it produces changes when you make a
+// repository, which is a thing that happens on a Tuesday, and working it out means listing your
+// home, asking the disk about every directory in it, and walking the ones no other sign has
+// already claimed. The board asked for it once a second, per open tab, for ever.
+//
+// Half a minute is not a compromise: a repository that turns up in the last column thirty seconds
+// late is a repository you have not finished making yet. And a repository with a story in it is
+// not affected at all — those come from the stories, which are not cached.
+const TTL = 30000
+let seen = { at: 0, list: null }
+
+/** Forgets the reading. For the tests, which make and unmake directories faster than a Tuesday. */
+export function forget() {
+  seen = { at: 0, list: null }
+}
+
 export function listProjects() {
+  if (seen.list && Date.now() - seen.at < TTL) return seen.list
+  const list = readProjects()
+  seen = { at: Date.now(), list }
+  return list
+}
+
+function readProjects() {
   const fromClaude = lastUsed()
   const mine = new Map(projectRecency().map((r) => [r.project_path, Number(r.at) || 0]))
-  // A repository with a card is always selectable, even if it lives outside your home — but
+  // A repository with a story is always selectable, even if it lives outside your home — but
   // only while its directory exists: the old name of a renamed one does not come back.
   const paths = new Set([...scan(fromClaude.keys()), ...[...mine.keys()].filter(exists)])
   // Your home is not a project: it is the directory that contains them all. It ends up here
@@ -113,7 +136,7 @@ export function listProjects() {
     path: dir,
     last_used: Math.max(fromClaude.get(dir) || 0, mine.get(dir) || 0),
     // Your stuff, or installed stuff? One sign is enough: a `.git`, a history in Claude Code, a
-    // card, a document in there, or the opposite of all of them — that there is nothing in it
+    // story, a document in there, or the opposite of all of them — that there is nothing in it
     // yet. Under your home there are also directories that are only ever programs, and those
     // stay out precisely because they are full of things nobody reads.
     // The empty question is asked last: it touches the disk, and by then only the few
@@ -130,23 +153,45 @@ export function listProjects() {
 }
 
 /**
- * The cards still standing: the ones whose directory exists. It is the same rule as the
- * repository list above — "a card is kept alive by its directory" — carried over to the board
- * too, which used to work its columns out from the cards alone. Without it, a deleted or
+ * The stories still standing: the ones whose directory exists. It is the same rule as the
+ * repository list above — "a story is kept alive by its directory" — carried over to the board
+ * too, which used to work its columns out from the stories alone. Without it, a deleted or
  * renamed directory leaves a column behind forever.
  *
- * Hide, do not delete: the cards stay in the database, and if the directory comes back one day
+ * Hide, do not delete: the stories stay in the database, and if the directory comes back one day
  * — an external disk remounted, a directory put back — so do they.
  *
- * The disk is asked once per repository and not once per card: there are a couple of dozen
- * columns and a few hundred cards, and this round runs every second.
+ * The disk is asked once per repository and not once per story: there are a couple of dozen
+ * columns and a few hundred stories, and this round runs every second.
  */
-export function onDisk(cards) {
+export function onDisk(stories) {
   const alive = new Map()
-  return cards.filter((c) => {
+  return stories.filter((c) => {
     if (!alive.has(c.project_path)) alive.set(c.project_path, exists(c.project_path))
     return alive.get(c.project_path)
   })
 }
 
 export const projectName = (p) => path.basename(p)
+
+/**
+ * The directories anything is allowed to open: the repositories k0 already knows, plus the ones
+ * sessions are really working in — which with a worktree are not the same thing. A path arriving
+ * from the address bar is not enough on its own: either it is in this list, or nothing is read.
+ *
+ * It lives here rather than beside the one endpoint that started it because three different parts
+ * of k0 now ask the same question — the file viewer, the backlog, the dev servers — and a second
+ * copy of "which directories are ours" is a second answer waiting to be the laxer one.
+ */
+export function rootOf(repo) {
+  if (!repo) return null
+  const roots = new Set(listProjects().map((p) => p.path))
+  // Both paths, and from the flattened row: `work_path` belongs to the session now, and a
+  // worktree that fell out of this list would make the viewer refuse exactly the sessions that
+  // most need it.
+  for (const story of listStories()) {
+    if (story.project_path) roots.add(story.project_path)
+    if (story.work_path) roots.add(story.work_path)
+  }
+  return roots.has(repo) ? repo : null
+}

package/server/servers.js

@@ -151,7 +151,7 @@ export function logPathFor(repo) {
  * repository, and the globe would then govern somebody else's server.
  *
  * Both separators count, rather than whichever one this machine happens to use. The paths on
- * either side come from different places — one from the operating system, one from a card or from
+ * either side come from different places — one from the operating system, one from a story or from
  * Claude Code's own files — and on Windows those two do not reliably agree on which slash they
  * write. Asking `path.sep` would make the answer depend on the machine reading it, which is how a
  * comparison starts being right in the tests and wrong in the field.
@@ -335,6 +335,27 @@ async function read() {
   }
 }
 
+/**
+ * Throws away the rows whose process is long gone, once, on the way up.
+ *
+ * A dev server is started detached and on purpose outlives k0 — see the note at the top of this
+ * file — so a row surviving a restart is normal and wanted. What is not wanted is a row surviving
+ * the *process*: the board had four of them, three pointing at pids that had died days earlier
+ * while the dev servers themselves were still running under new ones. k0 had lost them, and the
+ * only thing that kept finding them was the sighting on the port, which happens only while
+ * somebody is looking at the board.
+ *
+ * A pid is also a number the operating system hands out again. A row left pointing at a dead one
+ * is a row that will eventually point at somebody else's process, and `stop` acts on what the row
+ * says: this is what keeps that from being k0's problem.
+ */
+export function reconcile() {
+  for (const row of db.listDevServers()) {
+    if (row.pid && alive(row.pid)) continue
+    db.clearDevServer(row.project_path)
+  }
+}
+
 /** A reading, but only while somebody is looking. See machine.js, which lives by the same rule. */
 async function cycle() {
   if (Date.now() - watching > ATTENTION) return

package/server/sessions.js

@@ -5,7 +5,7 @@ import { StringDecoder } from 'node:string_decoder'
 import { PROJECTS_DIR } from './watcher.js'
 
 /**
- * Claude Code sessions that have already happened, ready to become cards.
+ * Claude Code sessions that have already happened, ready to become stories.
  *
  * Nothing is written here: it only reads ~/.claude/projects, where Claude Code keeps the
  * transcript of every session in a JSONL file.
@@ -109,7 +109,7 @@ function resolveRoot(cwd) {
   return cwd
 }
 
-function repoOf(cwd, cache) {
+export function repoOf(cwd, cache) {
   if (cache.has(cwd)) return cache.get(cwd)
   const r = resolveRoot(cwd)
   const ok =
@@ -238,13 +238,13 @@ function digest(file) {
 }
 
 /**
- * The sessions worth offering as cards, most recent first.
+ * The sessions worth offering as stories, most recent first.
  *
  * Two passes, because the second one is expensive: first the head of every transcript in the
  * window is checked, to keep only the real sessions and work out which repository they belong
  * to; then only the ones that actually fit under the per-repository cap are read in full.
  *
- * `exclude` are the session ids already on a card: re-importing must not make duplicates.
+ * `exclude` are the session ids already on a story: re-importing must not make duplicates.
  * `live` are the sessions still running, which can be attached too.
  * `root` only changes in the tests, to look at a directory of fake transcripts.
  */
@@ -316,7 +316,7 @@ export function scanSessions({
     for (const c of list) {
       if (taken >= perRepo) break
       const d = digest(c.file)
-      // Not one word of yours in the transcript: there is nothing for a card to say.
+      // Not one word of yours in the transcript: there is nothing for a story to say.
       if (!d.turns) continue
       taken++
       out.push({

package/server/settings.js

@@ -29,6 +29,8 @@ export const PATH = process.env.K0_CONFIG || path.join(HOME, 'config.json')
  */
 export const DEFAULTS = {
   closeIdleTerminalsAfterHours: 12,
+  backlog: true,
+  updateCheck: true,
 }
 
 /**
@@ -43,7 +45,9 @@ export const MIN_HOURS = 1
 /** The line k0 leaves at the top of the file, since JSON has nowhere else to put a word. */
 const NOTE =
   'k0 wrote this file and reads it again by itself whenever it changes — nothing to restart. ' +
-  'Delete a line to go back to its default. Hours at 0 switch that closing off entirely. ' +
+  'Delete a line to go back to its default. Hours at 0 switch that closing off entirely, and ' +
+  '"backlog": false puts the board back to what it was before epics and stories existed, and ' +
+  '"updateCheck": false stops the one question k0 asks npm. ' +
   'See Settings in the README.'
 
 /**
@@ -63,7 +67,26 @@ export function idleHours(raw) {
 /** A file's worth of anything, turned into settings that can be trusted. Pure: the tests live here. */
 export function normalise(raw) {
   const o = raw && typeof raw === 'object' ? raw : {}
-  return { closeIdleTerminalsAfterHours: idleHours(o.closeIdleTerminalsAfterHours) }
+  return {
+    closeIdleTerminalsAfterHours: idleHours(o.closeIdleTerminalsAfterHours),
+    backlog: onOff(o.backlog, DEFAULTS.backlog),
+    updateCheck: onOff(o.updateCheck, DEFAULTS.updateCheck),
+  }
+}
+
+/**
+ * Whether the backlog is there at all. It lives here rather than in the database because this is
+ * the file a person can actually open: a switch nobody can reach is not a switch, and `false`
+ * has to put the board back exactly as it was before any of this existed.
+ *
+ * Anything that is not plainly a no is a yes. `false`, `0`, `"off"` and `"no"` switch it off;
+ * a missing line, a typo, or a value nobody anticipated leaves the feature on, because losing
+ * your backlog to a mistyped setting is much worse than keeping a feature you meant to drop.
+ */
+export function onOff(raw, fallback = true) {
+  if (raw === undefined || raw === null || raw === '') return fallback
+  const v = String(raw).trim().toLowerCase()
+  return !(v === 'false' || v === '0' || v === 'off' || v === 'no')
 }
 
 let cached = null

package/server/sync.js

@@ -0,0 +1,383 @@
+import { execFileSync } from 'node:child_process'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import * as db from './db.js'
+import { HOME } from './paths.js'
+import * as cloud from './cloud.js'
+import * as mirror from './mirror.js'
+import { listProjects } from './projects.js'
+
+// ── Keeping the cloud's copy of the board ────────────────────────────────────
+// The board lives on this machine and keeps working with no network at all; the cloud holds a
+// copy of every row so it survives a lost laptop, reaches a second machine and can be read from a
+// browser. This file moves rows between the two. It never decides what the board means — that is
+// all in `db.js` — it only carries rows across, which is why it can afford to be dull.
+//
+// Three things happen on every round, in this order:
+//
+//   1. stories made offline get their real K number, oldest first;
+//   2. what changed here goes up (the `outbox` the triggers in `db.js` fill);
+//   3. what other machines changed comes down.
+//
+// A row travels as a document. Its references to other rows go by uid, because an integer id is
+// only meaningful in the database that handed it out.
+
+/** Which columns point at another row, and at which table. They travel as `<column>_uid`. */
+const REFS = {
+  epic: {},
+  story: { epic_id: 'epic', parent_story_id: 'story' },
+  session: { story_id: 'story' },
+  decision: { story_id: 'story', epic_id: 'epic', superseded_by: 'decision' },
+  decision_check: { story_id: 'story', decision_id: 'decision' },
+  round: { story_id: 'story', epic_id: 'epic' },
+  check_item: { story_id: 'story' },
+  dependency: { story_id: 'story', depends_on: 'story' },
+  story_log: { story_id: 'story' },
+}
+
+/** What stays on this machine: which terminal window, which folder, which commit it started at. */
+const LOCAL_ONLY = {
+  session: ['terminal_window_id', 'work_path', 'head_at_start'],
+}
+
+/**
+ * The order rows are written in on the way down, so that what a row points at is usually there
+ * already. Sessions do not come down at all: a session is a terminal on the machine that opened
+ * it, and the other machine has nothing to attach it to. Their status still goes up, for the web.
+ */
+const APPLY_ORDER = ['epic', 'story', 'decision', 'round', 'check_item', 'dependency', 'story_log', 'decision_check']
+
+// ── Which project a row is in ────────────────────────────────────────────────
+// A path means nothing on another machine. A project is named in the cloud by where its code
+// lives — the `origin` remote — so the same repository checked out in two places is one project.
+
+const projectIds = new Map()
+
+/** A repository's `origin`, cleaned of credentials and of the difference between ssh and https. */
+export function normaliseRemote(url) {
+  const raw = String(url || '').trim()
+  if (!raw) return ''
+  let host = ''
+  let repo = ''
+  const scp = /^[\w.-]+@([^:/]+):(.+)$/.exec(raw)
+  if (scp) {
+    host = scp[1]
+    repo = scp[2]
+  } else {
+    try {
+      const u = new URL(raw)
+      host = u.hostname
+      repo = u.pathname
+    } catch {
+      return raw.replace(/\.git$/, '')
+    }
+  }
+  return `${host.toLowerCase()}/${repo.replace(/^\/+/, '').replace(/\.git$/, '').replace(/\/+$/, '')}`
+}
+
+function remoteOf(dir) {
+  try {
+    return execFileSync('git', ['-C', dir, 'remote', 'get-url', 'origin'], {
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+  } catch {
+    return ''
+  }
+}
+
+/** A uid that is the same on every machine for the same repository: derived, not stored. */
+const derivedUid = (text) => {
+  const h = crypto.createHash('sha256').update(text).digest('hex')
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-5${h.slice(13, 16)}-${'89ab'[parseInt(h[16], 16) % 4]}${h.slice(17, 20)}-${h.slice(20, 32)}`
+}
+
+export function projectOf(projectPath) {
+  if (projectIds.has(projectPath)) return projectIds.get(projectPath)
+  const remote = normaliseRemote(remoteOf(projectPath))
+  // A repository with no remote is only ever on this machine, so its path is as good a name as any.
+  const uid = derivedUid(remote ? `remote:${remote}` : `path:${cloud.machine()}:${projectPath}`)
+  const p = { uid, remote, name: path.basename(projectPath || '') || projectPath }
+  projectIds.set(projectPath, p)
+  return p
+}
+
+// ── Up ───────────────────────────────────────────────────────────────────────
+
+/** One outbox line as the document the cloud keeps. */
+export function documentFor(entry) {
+  const row = entry.op === 'delete' ? null : db.syncRow(entry.tbl, entry.row_id)
+  if (!row) return { kind: entry.tbl, uid: entry.uid, deleted: true, data: {}, changed_at: entry.at }
+  const data = {}
+  const refs = REFS[entry.tbl] || {}
+  const skip = new Set(['_rowid', 'id', 'uid', ...(LOCAL_ONLY[entry.tbl] || [])])
+  for (const [k, v] of Object.entries(row)) {
+    if (skip.has(k)) continue
+    if (k in refs) data[`${k}_uid`] = db.uidOf(refs[k], v)
+    else data[k] = v
+  }
+  if ('project_path' in row) {
+    const p = projectOf(row.project_path)
+    data.project_uid = p.uid
+    data.project_name = p.name
+    data.project_remote = p.remote
+  }
+  return { kind: entry.tbl, uid: row.uid, deleted: false, data, changed_at: entry.at }
+}
+
+// ── Down ─────────────────────────────────────────────────────────────────────
+
+/** The local folder a project lives in here, if this machine has it; otherwise the path it came with. */
+function localPath(data) {
+  if (data.project_uid) {
+    for (const [p, info] of projectIds) if (info.uid === data.project_uid) return p
+  }
+  return data.project_path
+}
+
+/** Writes what came down. Returns how many rows were applied and how many were left for later. */
+export function apply(records) {
+  const waiting = new Set(db.outboxBatch(100000).map((e) => e.uid))
+  const order = (r) => {
+    const i = APPLY_ORDER.indexOf(r.kind)
+    return i < 0 ? APPLY_ORDER.length : i
+  }
+  const todo = records.filter((r) => r.kind in REFS && r.kind !== 'session').sort((a, b) => order(a) - order(b))
+  let applied = 0
+  let skipped = 0
+  db.applyRemote((put, drop) => {
+    for (const r of todo) {
+      // A change made here and not delivered yet is newer than anything the cloud can send back
+      // about the same row: it is what the person in front of this machine just did.
+      if (waiting.has(r.uid)) {
+        skipped++
+        continue
+      }
+      if (r.deleted) {
+        drop(r.kind, r.uid)
+        applied++
+        continue
+      }
+      const row = { uid: r.uid }
+      const refs = REFS[r.kind]
+      let missing = false
+      for (const [k, v] of Object.entries(r.data || {})) {
+        if (k.endsWith('_uid') && k.slice(0, -4) in refs) {
+          const col = k.slice(0, -4)
+          const id = db.idOfUid(refs[col], v)
+          if (v && id == null) missing = true
+          row[col] = id
+        } else if (!k.startsWith('project_') || k === 'project_path') {
+          row[k] = v
+        }
+      }
+      if ('project_path' in row) row.project_path = localPath(r.data)
+      // A row whose owner has not arrived is left for a later round rather than written pointing at
+      // nothing; the ones whose reference may be empty (an epic, a parent) are written without it.
+      const required = { session: 'story_id', decision_check: 'story_id', check_item: 'story_id', story_log: 'story_id', dependency: 'story_id' }
+      if (missing && required[r.kind] && row[required[r.kind]] == null) {
+        skipped++
+        continue
+      }
+      put(r.kind, row)
+      applied++
+    }
+  })
+  return { applied, skipped }
+}
+
+// ── The round ────────────────────────────────────────────────────────────────
+
+const state = { running: false, last: null, error: null, pushed: 0, pulled: 0, askedMe: 0 }
+
+export function status() {
+  return {
+    ...cloud.status(),
+    recording: db.syncRecording(),
+    pending: db.outboxSize(),
+    provisional: db.provisionalKeys().length,
+    needs_move: needsMove(),
+    last_sync: state.last,
+    sync_error: state.error,
+  }
+}
+
+// ── The first time ───────────────────────────────────────────────────────────
+// A board that existed before its owner signed in has numbers counted on this machine — per
+// repository, if it is older than k0 Cloud — and the cloud's counter starts somewhere else. Using
+// the cloud's numbers straight away would give a new story a K1 that the old board already has.
+// So nothing is recorded and no number comes from the cloud until the board has MOVED: renumbered
+// once, in the order its stories were made, starting where the cloud says, with a copy of the
+// database kept first. The person whose board it is sees every old number beside its new one and
+// says yes before any of it happens.
+
+const MOVED = 'cloud.moved'
+
+/** Signed in, let in, and the board on this machine still has to be moved to the account. */
+export function needsMove() {
+  return cloud.linked() && cloud.approved() && db.getPref(MOVED, '') !== String(cloud.me()?.id || '') && !db.boardIsEmpty()
+}
+
+/** What the move would do: every story and epic, its old key and its new one. Writes nothing. */
+export async function movePlan() {
+  const start = await peekNext()
+  const rows = db.renumberAll({ start, apply: false })
+  return { start, rows, texts: rows.textChanges || 0 }
+}
+
+/**
+ * The cloud's next number without using it up. There is no such call in the cloud on purpose — a
+ * number asked for is a number handed out — so this asks for one and the move then starts from
+ * exactly it; the preview is computed from the same number, and the counter is pushed past the
+ * whole board at the end.
+ */
+let peeked = null
+async function peekNext() {
+  if (peeked && Date.now() - peeked.at < 30 * 60_000 && peeked.who === cloud.me()?.id) return peeked.n
+  const n = await cloud.nextKey()
+  if (!n) throw new Error('k0 Cloud cannot be reached, so the board cannot be moved yet.')
+  peeked = { n, at: Date.now(), who: cloud.me()?.id }
+  return n
+}
+
+export const BACKUPS = path.join(HOME, 'backups')
+
+/** The move itself. A copy first, then the numbers, then the `.k0/` files, then the first sync. */
+export async function move() {
+  if (!cloud.linked() || !cloud.approved()) throw new Error('Sign in, and be let in, before moving the board.')
+  const start = await peekNext()
+  fs.mkdirSync(BACKUPS, { recursive: true })
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const backup = db.backupTo(path.join(BACKUPS, `k0-before-cloud-${stamp}.db`))
+  const rows = db.renumberAll({ start, apply: true })
+  const map = path.join(BACKUPS, `k0-before-cloud-${stamp}.keys.json`)
+  fs.writeFileSync(map, JSON.stringify(rows.map((r) => ({ kind: r.kind, project: r.project_path, title: r.title, old: r.old, new: r.new })), null, 2))
+  for (const r of rows) {
+    if (r.old === r.new) continue
+    try {
+      mirror.renameKey(r.kind, r.id, r.old)
+    } catch {
+      // `.k0/` reports its own errors where it is written; the numbers are moved regardless.
+    }
+  }
+  if (rows.length) await cloud.reserveKeys(start + rows.length - 1)
+  peeked = null
+  db.setPref(MOVED, String(cloud.me()?.id || ''))
+  attach()
+  await round()
+  return { moved: rows.length, start, backup, map }
+}
+
+/** Links the board to the account that just signed in: keys from the cloud, changes recorded. */
+export function attach() {
+  if (!cloud.linked() || !cloud.approved()) return false
+  if (db.boardIsEmpty() && db.getPref(MOVED, '') !== String(cloud.me()?.id || '')) db.setPref(MOVED, String(cloud.me()?.id || ''))
+  if (needsMove()) return false
+  db.useCloudKeys(true)
+  if (!db.syncRecording()) db.setSyncRecording(true, { snapshot: true })
+  return true
+}
+
+/** Signed out: keys are counted here again and nothing more is queued. */
+export function detach() {
+  db.useCloudKeys(false)
+  db.setSyncRecording(false)
+}
+
+async function giveRealKeys() {
+  for (const row of db.provisionalKeys()) {
+    const n = await cloud.nextKey()
+    if (!n) return
+    const was = db.assignKey(row.kind, row.id, n)
+    if (was) {
+      try {
+        mirror.renameKey(row.kind, row.id, was)
+      } catch {
+        // `.k0/` is a courtesy copy; its own errors are reported where it is written.
+      }
+    }
+  }
+}
+
+async function sendUp() {
+  for (let i = 0; i < 20; i++) {
+    const batch = db.outboxBatch(200)
+    if (!batch.length) return
+    await cloud.push(batch.map(documentFor))
+    db.outboxDone(batch)
+    state.pushed += batch.length
+  }
+}
+
+/** Every repository on this machine, named the way the cloud names it, once per run. */
+let known = false
+function learnProjects() {
+  if (known) return
+  known = true
+  try {
+    for (const p of listProjects()) projectOf(p.path)
+  } catch {
+    // Without the list a row from another machine keeps the path it came with: still on the
+    // board, just not openable here until the repository is.
+  }
+}
+
+async function bringDown() {
+  learnProjects()
+  for (let i = 0; i < 20; i++) {
+    const rows = await cloud.pull(cloud.pulledTo())
+    if (!rows.length) return
+    apply(rows)
+    cloud.setPulledTo(rows[rows.length - 1].seq)
+    state.pulled += rows.length
+    if (rows.length < 500) return
+  }
+}
+
+/** One round. Never throws: a sync that failed says so in `status()` and tries again next time. */
+export async function round() {
+  if (state.running || !cloud.enabled() || !cloud.linked()) return status()
+  state.running = true
+  try {
+    // Who this is is asked again every ten minutes, not only once: an account can be let in, or
+    // shut out, from the other side, and the board should notice without a restart.
+    if (!cloud.me() || Date.now() - state.askedMe > 10 * 60_000) {
+      await cloud.refreshMe()
+      state.askedMe = Date.now()
+    }
+    if (!cloud.approved()) {
+      // Signed in, waiting to be let in: ask again now and then, and do nothing else.
+      await cloud.refreshMe()
+      if (!cloud.approved()) return status()
+    }
+    if (!attach()) return status()
+    await giveRealKeys()
+    await sendUp()
+    await bringDown()
+    state.last = Date.now()
+    state.error = null
+  } catch (err) {
+    state.error = err.offline ? 'Offline — the board carries on and catches up when k0 Cloud is back.' : String(err.message || err)
+  } finally {
+    state.running = false
+  }
+  return status()
+}
+
+let timer = null
+
+/** Every few seconds while the server runs. Unref'd: the sync never keeps k0 alive by itself. */
+export function start(every = 5000) {
+  if (timer || !cloud.enabled()) return
+  if (cloud.linked() && cloud.approved()) attach()
+  timer = setInterval(() => round(), every)
+  timer.unref()
+  round()
+}
+
+export function stop() {
+  if (timer) clearInterval(timer)
+  timer = null
+}