k0-board 0.1.1 → 0.2.0

package/platform/shared/listeners.js

@@ -0,0 +1,121 @@
+/**
+ * Who is listening on which port, and where a process is working from.
+ *
+ * These are the two questions behind the globe in the column headings: a dev server is up if
+ * something it started holds a TCP port open, and a dev server somebody started by hand belongs
+ * to a repository if it is working from inside it.
+ *
+ * macOS and Linux answer both with the same `lsof`, in its field format, so one parser serves
+ * both — the same arrangement `ps.js` already has for the process table. Windows answers the
+ * first with PowerShell and cannot answer the second at all, which is exactly why the shape and
+ * not the command is what lives here.
+ *
+ * Nothing in this file opens a socket. It asks the operating system who is already holding one,
+ * which is both stronger evidence than a reply to a request and the only reading of "is it up"
+ * that k0 is allowed to take — see the rule about network requests in CLAUDE.md.
+ */
+
+/**
+ * lsof's field format is a stream of sets: `p<pid>` opens a process and every line after it
+ * belongs to that process until the next `p`. lsof emits `f<fd>` lines whether they were asked
+ * for or not, so anything that is not the field being read is stepped over rather than parsed.
+ *
+ * @param {string} out
+ * @param {string} field  the one-letter field to collect, `n` for both callers here
+ * @param {(pid: number, value: string) => void} take
+ */
+function eachField(out, field, take) {
+  let pid = null
+  for (const line of String(out ?? '').split('\n')) {
+    if (line[0] === 'p') {
+      const n = Number(line.slice(1))
+      pid = Number.isInteger(n) && n > 0 ? n : null
+    } else if (line[0] === field && pid !== null) {
+      take(pid, line.slice(1))
+    }
+  }
+}
+
+/**
+ * The port out of an address as lsof writes it: `*:4321`, `127.0.0.1:4321`, `[::1]:4321`.
+ * The last colon is the separator in all three, which is what makes IPv6 harmless here.
+ */
+export function portOf(address) {
+  const at = String(address ?? '').lastIndexOf(':')
+  if (at < 0) return null
+  const tail = address.slice(at + 1)
+  if (!/^\d+$/.test(tail)) return null
+  const port = Number(tail)
+  return port > 0 && port < 65536 ? port : null
+}
+
+/**
+ * `lsof -nP -iTCP -sTCP:LISTEN -F pn` as a map of pid to the ports it holds open.
+ * A process listening on both IPv4 and IPv6 shows the same port twice; the set folds them.
+ */
+export function parseListeners(out) {
+  const ports = new Map()
+  eachField(out, 'n', (pid, address) => {
+    const port = portOf(address)
+    if (port === null) return
+    if (!ports.has(pid)) ports.set(pid, new Set())
+    ports.get(pid).add(port)
+  })
+  return ports
+}
+
+/**
+ * `lsof -a -d cwd -p 1,2,3 -F n` as a map of pid to the directory it is working from.
+ * A process has exactly one, so the first answer for a pid is the answer.
+ */
+export function parseCwds(out) {
+  const cwds = new Map()
+  eachField(out, 'n', (pid, dir) => {
+    if (!cwds.has(pid) && dir) cwds.set(pid, dir)
+  })
+  return cwds
+}
+
+/**
+ * `ss -H -ltnp`, the answer on a Linux that has no lsof — which is most minimal ones, since
+ * `ss` comes with iproute2 and lsof does not come with anything.
+ *
+ *     LISTEN 0 511 *:4321 *:* users:(("node",pid=1234,fd=20))
+ *
+ * The listening address is the fourth column and the pids are in the tail, one process per
+ * `pid=`: a socket can be shared by a parent and its children, and then all of them own it.
+ */
+export function parseSs(out) {
+  const ports = new Map()
+  for (const line of String(out ?? '').split('\n')) {
+    const cols = line.trim().split(/\s+/)
+    if (cols.length < 4) continue
+    const port = portOf(cols[3])
+    if (port === null) continue
+    for (const m of line.matchAll(/pid=(\d+)/g)) {
+      const pid = Number(m[1])
+      if (!pid) continue
+      if (!ports.has(pid)) ports.set(pid, new Set())
+      ports.get(pid).add(port)
+    }
+  }
+  return ports
+}
+
+/**
+ * `Get-NetTCPConnection -State Listen` piped through `ConvertTo-Csv`, which is how Windows
+ * answers the same question. Two columns, `LocalPort` and `OwningProcess`, in that order.
+ */
+export function parseNetTcp(out) {
+  const ports = new Map()
+  for (const line of String(out ?? '').split('\n')) {
+    const m = /^"?(\d+)"?\s*,\s*"?(\d+)"?\s*$/.exec(line.trim())
+    if (!m) continue
+    const port = Number(m[1])
+    const pid = Number(m[2])
+    if (!pid || port <= 0 || port >= 65536) continue
+    if (!ports.has(pid)) ports.set(pid, new Set())
+    ports.get(pid).add(port)
+  }
+  return ports
+}

package/platform/shared/servers.js

@@ -0,0 +1,111 @@
+/**
+ * Dev servers, the parts that are the same on macOS and Linux.
+ *
+ * Both have `lsof`, both have a `ps` that knows about process groups, and both signal a whole
+ * group by signalling a negative pid. What they do not share is how to ask where a process is
+ * working from — macOS goes through lsof, Linux reads a symlink — so that one stays with each
+ * adapter and only the rest is here.
+ */
+
+import { runQuiet, which, alive } from './run.js'
+import { parseListeners, parseCwds, parseSs } from './listeners.js'
+
+export const LSOF = () => which('lsof', ['/usr/sbin/lsof', '/usr/bin/lsof'])
+const SS = () => which('ss', ['/usr/sbin/ss', '/usr/bin/ss', '/sbin/ss'])
+const PS = () => which('ps', ['/bin/ps', '/usr/bin/ps'])
+
+// Asking the whole machine who is listening is not free — measured in the hundreds of
+// milliseconds on a busy laptop — so the caller is expected to do it rarely. See the sampling
+// discipline in server/servers.js, which is the one machine.js already lives by.
+const TIMEOUT = 8000
+
+/**
+ * How to run a project's own command. A LOGIN shell, so that a version manager's PATH and the
+ * project's own `.nvmrc` are in force — under a launch agent the inherited PATH is barely more
+ * than /usr/bin:/bin, and `npm` would simply not be found. It is the same reason `findClaude`
+ * ends up asking a shell.
+ */
+export const shell = (command) => ({
+  file: process.env.SHELL || '/bin/sh',
+  args: ['-lc', command],
+})
+
+/** Everything holding a TCP port open, from lsof. */
+export async function lsofListeners() {
+  const bin = LSOF()
+  if (!bin) return new Map()
+  return parseListeners(await runQuiet(bin, ['-nP', '-iTCP', '-sTCP:LISTEN', '-F', 'pn'], { timeout: TIMEOUT }))
+}
+
+/** The same, from iproute2 — which a minimal Linux has when it has no lsof. */
+export async function ssListeners() {
+  const bin = SS()
+  if (!bin) return new Map()
+  return parseSs(await runQuiet(bin, ['-H', '-l', '-t', '-n', '-p'], { timeout: TIMEOUT }))
+}
+
+/** Where each of these processes is working from, from lsof. */
+export async function lsofCwds(pids) {
+  const bin = LSOF()
+  if (!bin || !pids.length) return new Map()
+  return parseCwds(await runQuiet(bin, ['-a', '-d', 'cwd', '-p', pids.join(','), '-F', 'n'], { timeout: TIMEOUT }))
+}
+
+/**
+ * The process group a pid belongs to. Empty when the process is already gone, which is not an
+ * error: it is the answer.
+ */
+export async function pgidOf(pid) {
+  const bin = PS()
+  if (!bin || !pid) return null
+  const pgid = Number(String(await runQuiet(bin, ['-o', 'pgid=', '-p', String(pid)])).trim())
+  return Number.isInteger(pgid) && pgid > 1 ? pgid : null
+}
+
+/**
+ * Stop a dev server and everything it started.
+ *
+ * Signalling the group rather than the process is the whole point. `npm run dev` is a shell
+ * that spawns `vite`, and a SIGTERM to npm alone leaves vite holding the port — which is
+ * precisely what the old per-repo skill was working around with `pkill -f "astro dev"`.
+ *
+ * But the group is only signalled when `root` is the group's LEADER, and that restraint is not
+ * pedantry. A server k0 started is `detached`, so it leads its own group and the fast path is
+ * always taken. A server somebody started by hand is a different matter: under job control its
+ * group leader is the npm it was typed as, but in a script, or under a shell with job control
+ * off, the group can be the SHELL's — and signalling that would close the user's terminal to
+ * stop a dev server. So when `root` does not lead the group, the pids are signalled one by one
+ * instead, children before parents, which is slower and cannot take anything with it that the
+ * caller did not name.
+ *
+ * @param {number} root  the topmost process of the server
+ * @param {number[]} pids  every process under it, `root` included — see `subtree` in machine.js
+ * @param {'SIGTERM'|'SIGKILL'} signal
+ */
+export async function stop(root, pids, signal = 'SIGTERM') {
+  if (!root) return false
+  const pgid = await pgidOf(root)
+  if (pgid === root) {
+    try {
+      process.kill(-pgid, signal)
+      return true
+    } catch {
+      // Already gone between the question and the signal. Fall through: the loop below is
+      // harmless on a dead process and is what answers honestly.
+    }
+  }
+  let touched = false
+  // Youngest first — a higher pid is a later process, which in a tree grown in one go is the
+  // child. It is a tendency and not a guarantee, but the order only decides who sees its parent
+  // disappear first, and SIGTERM reaches all of them either way.
+  for (const pid of [...new Set([...pids, root])].sort((a, b) => b - a)) {
+    if (!alive(pid)) continue
+    try {
+      process.kill(pid, signal)
+      touched = true
+    } catch {
+      /* it went on its own between the check and the signal */
+    }
+  }
+  return touched
+}

package/platform/win32/index.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import * as terminal from './terminal.js'
 import * as power from './power.js'
 import * as metrics from './metrics.js'
+import * as servers from './servers.js'
 import * as shell from './shell.js'
 import * as service from './service.js'
 import { NO_CAPABILITIES } from '../contract.js'
@@ -19,6 +20,7 @@ export const capabilities = {
   terminal: terminal.capabilities(),
   power: power.capabilities(),
   metrics: metrics.capabilities(),
+  servers: servers.capabilities(),
   service: service.capabilities(),
   tray: hasPowerShell(),
   revealInFileManager: true,
@@ -45,9 +47,21 @@ export const notes = {
           'PowerShell was not found. k0 needs it to open, place and raise terminal windows on ' +
           'Windows.',
       }),
+  'servers.adopt':
+    'Windows does not let one process read another’s working directory, so k0 cannot tell ' +
+    'which repository a dev server you started yourself belongs to. The globe switches on and ' +
+    'off the servers k0 started, and says nothing about the others rather than showing them ' +
+    'as off.',
+  ...(hasPowerShell()
+    ? {}
+    : {
+        'servers.ports':
+          'PowerShell was not found, so k0 cannot see which port a dev server is listening on. ' +
+          'It can still start and stop one, but the globe cannot open it for you.',
+      }),
 }
 
-export { terminal, power, metrics, shell, service }
+export { terminal, power, metrics, servers, shell, service }
 
 /** Nothing on Windows reaches outside k0's own files, so there is nothing to consent to. */
 export const extras = []

package/platform/win32/servers.js

@@ -0,0 +1,73 @@
+import { psJson, psQuiet, POWERSHELL } from './powershell.js'
+import { which, runQuiet } from '../shared/run.js'
+
+/**
+ * Dev servers on Windows.
+ *
+ * Listening sockets come from `Get-NetTCPConnection`, which has carried an owning process id
+ * since Windows 8 and needs nothing installed. Stopping goes through `taskkill /T`, which walks
+ * the tree itself — Windows has no process groups to signal, and killing `npm` alone would
+ * leave the server holding the port exactly as it does everywhere else.
+ *
+ * What Windows will not answer is where another process is working from. There is no /proc and
+ * no lsof; getting it means opening the process and reading its PEB, which is a native module,
+ * and k0 has no dependencies. So adoption is off here and the interface SAYS so — a server
+ * somebody started by hand is reported as unknown rather than drawn as off. See the note in
+ * index.js, which is the sentence the board shows.
+ */
+const hasPowerShell = () => !!POWERSHELL()
+
+export const capabilities = () => ({
+  run: true,
+  ports: hasPowerShell(),
+  adopt: false,
+})
+
+export async function listeners() {
+  if (!hasPowerShell()) return new Map()
+  const rows = await psJson(
+    '@(Get-NetTCPConnection -State Listen | Select-Object LocalPort, OwningProcess)',
+    []
+  )
+  const ports = new Map()
+  for (const row of Array.isArray(rows) ? rows : [rows].filter(Boolean)) {
+    const pid = Number(row.OwningProcess)
+    const port = Number(row.LocalPort)
+    if (!pid || port <= 0 || port >= 65536) continue
+    if (!ports.has(pid)) ports.set(pid, new Set())
+    ports.get(pid).add(port)
+  }
+  return ports
+}
+
+/** Windows cannot say. An empty map is the honest answer, and `capabilities.adopt` explains it. */
+export async function cwds() {
+  return new Map()
+}
+
+/**
+ * `/T` takes the children with it and `/F` does not ask twice. There is no gentle signal on
+ * Windows worth sending first: a console application gets CTRL_BREAK or nothing, and nothing
+ * is what a detached one gets.
+ */
+export async function stop(root) {
+  if (!root) return false
+  const taskkill = which('taskkill', ['C:\\Windows\\System32\\taskkill.exe'])
+  if (taskkill) {
+    await runQuiet(taskkill, ['/PID', String(root), '/T', '/F'], { timeout: 8000 })
+    return true
+  }
+  if (!hasPowerShell()) return false
+  await psQuiet(`Stop-Process -Id ${Number(root)} -Force -ErrorAction SilentlyContinue`)
+  return true
+}
+
+/**
+ * Windows has no login shell whose PATH is worth inheriting, and `npm` is a `.cmd` that only
+ * the command processor knows how to run. `/d` skips whatever AutoRun command the registry
+ * would otherwise inject ahead of it.
+ */
+export const shell = (command) => ({
+  file: process.env.COMSPEC || 'cmd.exe',
+  args: ['/d', '/s', '/c', command],
+})

package/platform/win32/tray.ps1

@@ -74,6 +74,16 @@ $notify.Visible = $true
 $menu = New-Object System.Windows.Forms.ContextMenuStrip
 $notify.ContextMenuStrip = $menu
 
+# Clicking the balloon brings that session's terminal up front, which is the whole point of being
+# told. Windows shows one balloon at a time and replaces it rather than queueing, so the card the
+# click belongs to is always the last one announced — there is nothing else it could be.
+$script:LastNotified = $null
+$notify.Add_BalloonTipClicked({
+    if ($null -ne $script:LastNotified) {
+      Invoke-K0 "/api/card/$($script:LastNotified)/focus" @{} | Out-Null
+    }
+  }) | Out-Null
+
 function Add-K0Item($Text, $Action, [bool]$Enabled = $true) {
   $item = New-Object System.Windows.Forms.ToolStripMenuItem
   $item.Text = $Text
@@ -124,6 +134,7 @@ function Show-K0Notifications($Waiting) {
     foreach ($card in $Waiting) {
       $key = "$($card.id):$($card.status)"
       if (-not $script:Seen.ContainsKey($key)) {
+        $script:LastNotified = $card.id
         $notify.BalloonTipTitle = $Labels[$card.status]
         $notify.BalloonTipText = $card.title
         $notify.ShowBalloonTip(4000)

package/server/changelog.js

@@ -0,0 +1,242 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import * as db from './db.js'
+import * as git from './git.js'
+import { listProjects, projectName } from './projects.js'
+
+// ── What you have been doing ─────────────────────────────────────────────────
+// The board says what is happening now. This says what happened, which is a different
+// question and needs a different source: git already keeps that diary, perfectly, and has
+// been keeping it since long before k0 existed.
+//
+// So nothing here is stored. There is no table, no nightly run, no index to keep in step with
+// reality — the facts are read from git and from `session_event` when somebody asks for them.
+// A cache would be wrong more often than it helped anyway: "today" changes while you are
+// reading it, and "this week" contains today.
+//
+// This module gathers. It writes no prose and calls no model: that is `writer.js`.
+
+const DAY = 24 * 60 * 60 * 1000
+const LOOKBACK = 30 * DAY // how far back "the last day you worked" is willing to look
+const CONCURRENCY = 4 // git processes at once: enough to be quick, few enough to stay polite
+const CHANGELOG_HEAD = 64 * 1024 // `[Unreleased]` lives at the top; the rest is history
+
+export const PERIODS = ['today', 'yesterday', 'week', 'month']
+
+const startOfDay = (t) => {
+  const d = new Date(t)
+  d.setHours(0, 0, 0, 0)
+  return d.getTime()
+}
+
+/**
+ * The four windows, in local time, because a day is a day where the person is — not where the
+ * server thinks it is. `week` and `month` roll backwards from today rather than snapping to a
+ * calendar Monday or a first of the month: on the 2nd, a calendar month would be two days.
+ *
+ * `last` is not here: which day that is depends on the data, so it is decided in `facts()`.
+ */
+export function windowFor(period, now = Date.now()) {
+  const today = startOfDay(now)
+  const tomorrow = today + DAY
+  if (period === 'today') return { period, from: today, to: tomorrow }
+  if (period === 'yesterday') return { period, from: today - DAY, to: today }
+  if (period === 'week') return { period, from: today - 6 * DAY, to: tomorrow }
+  if (period === 'month') return { period, from: today - 29 * DAY, to: tomorrow }
+  return null
+}
+
+/**
+ * The most recent day that has anything in it — the one the page opens on.
+ *
+ * Not "yesterday": on a Monday yesterday is Sunday, and a page that opens empty after every
+ * weekend teaches you not to open it. This is the same idea `web/recency.js` already uses to
+ * decide which columns are still warm — anchored to the work rather than to the clock.
+ */
+export function lastActiveDay(stamps, now = Date.now()) {
+  let best = null
+  for (const t of stamps) {
+    if (!Number.isFinite(t) || t > now) continue
+    if (best === null || t > best) best = t
+  }
+  return best === null ? null : startOfDay(best)
+}
+
+/**
+ * The `[Unreleased]` lines of a Keep a Changelog file: written down, not yet released.
+ * Everything from that heading to the next one at the same level or higher.
+ */
+export function unreleasedSection(md) {
+  const lines = String(md ?? '').split('\n')
+  const start = lines.findIndex((l) => /^#{1,3}\s*\[?unreleased\]?/i.test(l))
+  if (start === -1) return null
+  const depth = (/^(#+)/.exec(lines[start]) || [, '##'])[1].length
+  const out = []
+  for (let i = start + 1; i < lines.length; i++) {
+    const m = /^(#+)\s/.exec(lines[i])
+    if (m && m[1].length <= depth) break
+    const line = lines[i].trim()
+    if (line) out.push(line)
+  }
+  return out.length ? out : null
+}
+
+/**
+ * Does this repository belong in the summary at all?
+ *
+ * This is the rule that keeps the page honest. A repository that has been dirty since March
+ * and that you have not opened since is not news, and a summary that repeats it every single
+ * morning is a summary you stop reading. Something has to have happened IN the window — a
+ * commit, a file saved, a card moved — and only then is it worth saying what is still
+ * outstanding there.
+ */
+export function isActive(repo) {
+  return !!(repo && (repo.commits.length || repo.dirty.length || repo.cards.length))
+}
+
+/** Keeps only what falls inside a window, and drops the repositories left with nothing. */
+export function narrow(repos, from, to) {
+  const inside = (t) => Number.isFinite(t) && t >= from && t < to
+  return repos
+    .map((r) => ({
+      ...r,
+      commits: r.commits.filter((c) => inside(Date.parse(c.at))),
+      dirty: r.dirty.filter((f) => inside(f.at)),
+      cards: r.cards.filter((c) => inside(c.touched)),
+    }))
+    .filter(isActive)
+}
+
+/** Runs the work a few at a time: dozens of repositories must not become dozens of processes. */
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length)
+  let next = 0
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    for (let i = next++; i < items.length; i = next++) out[i] = await fn(items[i], i)
+  })
+  await Promise.all(workers)
+  return out
+}
+
+function unreleasedOf(dir) {
+  const file = path.join(dir, 'CHANGELOG.md')
+  try {
+    const fd = fs.openSync(file, 'r')
+    try {
+      const buf = Buffer.alloc(CHANGELOG_HEAD)
+      const read = fs.readSync(fd, buf, 0, CHANGELOG_HEAD, 0)
+      return unreleasedSection(buf.subarray(0, read).toString('utf8'))
+    } finally {
+      fs.closeSync(fd)
+    }
+  } catch {
+    return null // no changelog is the normal case, not a problem to report
+  }
+}
+
+/** When each hanging file was last saved. A path that has vanished under us is simply skipped. */
+function stampDirty(dir, paths) {
+  const out = []
+  for (const rel of paths) {
+    try {
+      out.push({ path: rel, at: fs.statSync(path.join(dir, rel)).mtimeMs })
+    } catch {
+      /* gone between the listing and the stat */
+    }
+  }
+  return out
+}
+
+async function gather(from, to) {
+  const projects = listProjects().filter((p) => fs.existsSync(path.join(p.path, '.git')))
+  const cards = db.eventsBetween(from, to)
+  const byRepo = new Map()
+  for (const c of cards) {
+    if (!byRepo.has(c.project_path)) byRepo.set(c.project_path, [])
+    byRepo.get(c.project_path).push(c)
+  }
+
+  const repos = await mapLimit(projects, CONCURRENCY, async (p) => {
+    const [h, dirty] = await Promise.all([git.history(p.path, { from, to }), git.dirtyFiles(p.path)])
+    if (!h) return null
+    return {
+      name: projectName(p.path),
+      path: p.path,
+      remote: h.remote,
+      unpushedTotal: h.unpushedTotal,
+      commits: h.commits.map((c) => ({
+        sha: c.sha.slice(0, 7),
+        at: c.at,
+        subject: c.subject,
+        body: c.body,
+        online: c.online,
+      })),
+      dirty: stampDirty(p.path, dirty),
+      dirtyTotal: dirty.length,
+      unreleased: unreleasedOf(p.path),
+      cards: (byRepo.get(p.path) ?? []).map((c) => ({
+        title: c.title,
+        description: c.description || '',
+        status: c.status,
+        touched: c.touched,
+        done: c.status === 'COMPLETED',
+      })),
+    }
+  })
+  return repos.filter(Boolean)
+}
+
+/** The one-line arithmetic the page and the writer both need, worked out once. */
+export function totals(repos) {
+  let commits = 0
+  let online = 0
+  let local = 0
+  let dirty = 0
+  let cardsOpen = 0
+  let cardsDone = 0
+  for (const r of repos) {
+    commits += r.commits.length
+    for (const c of r.commits) {
+      if (c.online === true) online++
+      else if (c.online === false) local++
+    }
+    dirty += r.dirty.length
+    for (const c of r.cards) {
+      if (c.done) cardsDone++
+      else cardsOpen++
+    }
+  }
+  return { repositories: repos.length, commits, online, local, dirty, cardsOpen, cardsDone }
+}
+
+/**
+ * Everything the page and the writer work from. Reads git and the board; touches nothing.
+ *
+ * `last` costs the same as any other period even though it does not know its own window yet:
+ * one pass over the lookback answers both "which day was the last one" and "what happened on
+ * it", because a month of `git log` is the same single process as a day of it.
+ */
+export async function facts(period, now = Date.now()) {
+  const wanted = windowFor(period, now)
+  const scan = wanted ?? { period: 'last', from: startOfDay(now) - LOOKBACK, to: startOfDay(now) + DAY }
+  const gathered = await gather(scan.from, scan.to)
+
+  let { from, to } = scan
+  let resolved = scan.period
+  if (!wanted) {
+    const stamps = []
+    for (const r of gathered) {
+      for (const c of r.commits) stamps.push(Date.parse(c.at))
+      for (const f of r.dirty) stamps.push(f.at)
+      for (const c of r.cards) stamps.push(c.touched)
+    }
+    const day = lastActiveDay(stamps, now)
+    // Nothing at all in the last month: rather than an arbitrary day, show today and say so.
+    from = day ?? startOfDay(now)
+    to = from + DAY
+    resolved = 'last'
+  }
+
+  const repos = narrow(gathered, from, to).sort((a, b) => b.commits.length - a.commits.length || a.name.localeCompare(b.name))
+  return { period: resolved, from, to, repos, totals: totals(repos) }
+}

package/server/db.js

@@ -52,6 +52,18 @@ db.exec(`
     "key"   TEXT PRIMARY KEY,
     "value" TEXT NOT NULL
   );
+
+  -- The dev server k0 started for a repository, and is therefore responsible for. It is
+  -- deliberately not a record of what is RUNNING — that is read from the machine every few
+  -- seconds and nothing here could be trusted to keep up with it. It is a record of intent:
+  -- a row means "k0 started this and it is meant to be up", which is what tells a server that
+  -- fell over apart from one that was switched off. Stopping deletes the row.
+  CREATE TABLE IF NOT EXISTS dev_server (
+    project_path TEXT PRIMARY KEY,
+    pid          INTEGER NOT NULL,
+    command      TEXT NOT NULL,
+    started_at   INTEGER NOT NULL
+  );
 `)
 
 // Additive migrations: the column may be missing from a database created before it existed.
@@ -230,6 +242,28 @@ export function deleteCard(id) {
   db.prepare('DELETE FROM card WHERE id = ?').run(id)
 }
 
+/**
+ * The cards that moved inside a window, one row each, with where they got to.
+ *
+ * `session_event` has been keeping this diary since the beginning — a row every time a card
+ * really changes status, and none when nothing happens — and until now the only thing anybody
+ * ever asked it was how old the current status is. This is the first question that reads it as
+ * what it is: a history.
+ *
+ * `touched` is when the card last moved inside the window, not when it moved last: a card
+ * finished on Tuesday belongs to Tuesday even if it was reopened on Friday.
+ */
+export function eventsBetween(from, to) {
+  return db.prepare(`
+    SELECT c.id, c.title, c.description, c.project_path, c.status, c.completed_at,
+           MAX(e.at) AS touched, COUNT(e.id) AS moves
+    FROM session_event e JOIN card c ON c.id = e.card_id
+    WHERE e.at >= ? AND e.at < ?
+    GROUP BY c.id
+    ORDER BY touched DESC
+  `).all(from, to)
+}
+
 // ── The switches that remember ───────────────────────────────────────────────
 /** The caller decides what a missing row means: this returns `fallback`. */
 export function getPref(key, fallback = null) {
@@ -249,6 +283,30 @@ export function dropPref(key) {
   db.prepare('DELETE FROM pref WHERE "key" = ?').run(key)
 }
 
+// ── The dev servers k0 started ───────────────────────────────────────────────
+// See the comment on the table: a row is intent, not observation.
+
+export function listDevServers() {
+  return db.prepare('SELECT project_path, pid, command, started_at FROM dev_server').all()
+}
+
+export function getDevServer(projectPath) {
+  return db.prepare('SELECT project_path, pid, command, started_at FROM dev_server WHERE project_path = ?')
+    .get(projectPath) ?? null
+}
+
+export function setDevServer(projectPath, { pid, command, startedAt }) {
+  db.prepare(`
+    INSERT INTO dev_server (project_path, pid, command, started_at) VALUES (?, ?, ?, ?)
+    ON CONFLICT(project_path) DO UPDATE SET
+      pid = excluded.pid, command = excluded.command, started_at = excluded.started_at
+  `).run(projectPath, pid, command, startedAt)
+}
+
+export function clearDevServer(projectPath) {
+  db.prepare('DELETE FROM dev_server WHERE project_path = ?').run(projectPath)
+}
+
 /**
  * Letting go of the file. It matters in exactly one place — a test that wants to delete the
  * database it was pointed at — and it matters on exactly one platform: POSIX lets a file be