k0-board 0.2.0 → 0.4.0

package/server/files.js

@@ -36,6 +36,29 @@ const DOC_EXT = new Set([
 
 export const isDoc = (p) => DOC_EXT.has(path.extname(p).toLowerCase())
 
+// The other half of what is worth listing: the files that say how a project is set up. They are
+// not documents — nobody prints an `.env` — but they are the ones you go looking for by hand, and
+// until now the viewer was the only place in k0 you could not reach them from. They stay behind a
+// switch in the page, because in a repository of prose they would only be noise.
+const CONFIG_EXT = new Set(['.json', '.yml', '.yaml', '.toml', '.ini', '.cfg', '.conf'])
+
+// `.env.local` has extension `.local`, and `.env` has no extension at all: this rule reads the
+// name, not the end of it, or the commonest file of the lot would be the one that got away.
+const ENV_NAME = /^\.env(\..+)?$/
+
+export const isConfig = (p) =>
+  CONFIG_EXT.has(path.extname(p).toLowerCase()) || ENV_NAME.test(path.basename(p))
+
+/** Everything the listing carries: documents to read, configuration to check. */
+export const isListed = (p) => isDoc(p) || isConfig(p)
+
+// What can be written back from the page. Configuration, and the notes kept next to it — never
+// code: k0 is not an editor, and a `.js` changed in a browser tab with no undo and no syntax
+// check is a good way to break a project without noticing.
+const NOTE_EXT = new Set(['.md', '.markdown', '.mdx', '.txt'])
+
+export const isEditable = (p) => NOTE_EXT.has(path.extname(p).toLowerCase()) || isConfig(p)
+
 // ── What kind of file is this ─────────────────────────────────────────────────
 const MARKDOWN = new Set(['.md', '.markdown', '.mdx'])
 
@@ -213,7 +236,17 @@ const cache = new Map()
  */
 async function scan(root) {
   const names = hasGit() && fs.existsSync(path.join(root, '.git')) ? await tracked(root) : null
-  return { git: !!names, ...(names ? withStats(root, names) : walk(root)) }
+  if (!names) return { git: false, ...walk(root, isListed) }
+
+  // git's listing is missing exactly the file all this was built for: an `.env` is ignored by
+  // definition, so `ls-files -co --exclude-standard` will never name it. So the disk is walked a
+  // second time for configuration alone — a handful of names, under the same bounds as the other
+  // walk — and what git already gave is kept as it is.
+  const fromGit = withStats(root, names)
+  const seen = new Set(fromGit.files.map((f) => f.p))
+  const extra = walk(root, isConfig)
+  for (const f of extra.files) if (!seen.has(f.p)) fromGit.files.push(f)
+  return { git: true, files: fromGit.files, truncated: fromGit.truncated || extra.truncated }
 }
 
 const tracked = (root) =>
@@ -226,14 +259,14 @@ function withStats(root, names) {
   const files = []
   let truncated = false
   for (const p of names) {
-    if (!isDoc(p)) continue
+    if (!isListed(p)) continue
     if (files.length >= MAX_FILES) {
       truncated = true
       break
     }
     try {
       const s = fs.statSync(path.join(root, p))
-      if (s.isFile()) files.push({ p, m: Math.floor(s.mtimeMs), s: s.size })
+      if (s.isFile()) files.push(entry(p, s))
     } catch {
       /* deleted between the listing and now */
     }
@@ -241,7 +274,18 @@ function withStats(root, names) {
   return { files, truncated }
 }
 
-function walk(root) {
+/**
+ * One row of the listing. `c` marks a configuration file, so the page can leave it out without
+ * having to ask a second time: one byte on the wire, one switch on the other side.
+ */
+const entry = (p, s) => {
+  const row = { p, m: Math.floor(s.mtimeMs), s: s.size }
+  if (isConfig(p)) row.c = 1
+  return row
+}
+
+/** Everything under `root` that `pick` accepts. */
+function walk(root, pick) {
   const files = []
   let truncated = false
 
@@ -258,18 +302,20 @@ function walk(root) {
         truncated = true
         return
       }
-      if (e.name.startsWith('.')) continue
+      // A directory whose name starts with a dot is skipped whole: that one rule removes .git,
+      // the caches and the virtual environments in a single stroke. A dotted *file* is not —
+      // `.env` is a dotted name, and it is the one this walk was taught to find.
       const child = path.join(dir, e.name)
       const childRel = rel ? `${rel}/${e.name}` : e.name
       if (e.isDirectory()) {
-        if (!SKIP.has(e.name)) rec(child, childRel, depth + 1)
+        if (!e.name.startsWith('.') && !SKIP.has(e.name)) rec(child, childRel, depth + 1)
         continue
       }
       // No symbolic links: a loop would send the walk round forever.
-      if (!e.isFile() || !isDoc(e.name)) continue
+      if (!e.isFile() || !pick(e.name)) continue
       try {
         const s = fs.statSync(child)
-        files.push({ p: childRel, m: Math.floor(s.mtimeMs), s: s.size })
+        files.push(entry(childRel, s))
       } catch {
         /* gone in the meantime */
       }
@@ -392,9 +438,9 @@ export async function changed(root, headAtStart) {
           .catch(() => []) // the starting commit may not be there any more
       : [],
   ])
-  // Documents only here too: a "Changed 40" made of `.tsx` files would say there are forty
-  // things to read, when there is nothing to read at all.
-  return [...new Set([...now, ...mine])].filter(isDoc)
+  // What the listing carries, here too: a "Changed 40" made of `.tsx` files would say there are
+  // forty things to read, when there is nothing to read at all.
+  return [...new Set([...now, ...mine])].filter(isListed)
 }
 
 // ── Searching inside the files ────────────────────────────────────────────────
@@ -406,6 +452,8 @@ export async function changed(root, headAtStart) {
 // of a few KB, all already in the operating system's cache — it costs less than keeping an
 // index up to date, and an index goes stale.
 const TEXTY = new Set(['.md', '.markdown', '.mdx', '.txt', '.html', '.htm'])
+/** Read only when the page asks for them: they are hidden by default, and so are their lines. */
+const TEXTY_CONFIG = new Set(['.json', '.yml', '.yaml', '.toml', '.ini', '.cfg', '.conf'])
 const GREP_FILES = 80 // how many results are enough: past that nobody scrolls anyway
 const GREP_BYTES = 1 << 20
 const SNIPPET = 200
@@ -421,8 +469,13 @@ export const plain = (s) =>
     .toLowerCase()
     .replace(/[\u00C0-\u024F]/g, (c) => c.normalize('NFD')[0])
 
-/** The documents that contain all the words searched for, with the line they appear on. */
-export async function grep(root, query) {
+/**
+ * The documents that contain all the words searched for, with the line they appear on.
+ *
+ * With `nerd` the configuration files are looked inside as well. It has to follow what the page
+ * is showing: finding a line in a file the listing is hiding would be a result you cannot open.
+ */
+export async function grep(root, query, nerd = false) {
   const words = plain(query).split(/\s+/).filter(Boolean)
   if (!words.length) return []
 
@@ -430,7 +483,10 @@ export async function grep(root, query) {
   const hits = []
   for (const f of files) {
     if (hits.length >= GREP_FILES) break
-    if (!TEXTY.has(path.extname(f.p).toLowerCase()) || f.s > GREP_BYTES) continue
+    if (f.c && !nerd) continue
+    const ext = path.extname(f.p).toLowerCase()
+    const texty = TEXTY.has(ext) || (nerd && (TEXTY_CONFIG.has(ext) || ENV_NAME.test(path.basename(f.p))))
+    if (!texty || f.s > GREP_BYTES) continue
     let text
     try {
       text = fs.readFileSync(path.join(root, f.p), 'utf8')
@@ -484,5 +540,40 @@ export function read(abs) {
   return { kind, ...meta, text, truncated }
 }
 
+/**
+ * Writes the file back, or refuses.
+ *
+ * `was` is the modification time the page was handed when it opened the file. If the file on disk
+ * has moved on since, the write does not happen: somebody else — a session, an editor, a script —
+ * has written it in the meantime, and overwriting silently would throw their work away. The page
+ * is told, and it still has what you typed.
+ *
+ * The bytes go to a neighbouring name and are then renamed over the original, which on the same
+ * filesystem is one indivisible step: an interrupted save leaves the old file whole rather than
+ * half the new one. The mode is carried over, or a `.env` at 600 would come back readable by all.
+ */
+export function write(abs, text, was) {
+  const s = fs.statSync(abs)
+  if (!s.isFile()) throw new Error('Not a file')
+  if (Math.floor(s.mtimeMs) !== was) {
+    const clash = new Error('This file changed on disk while you were editing it. Nothing was saved.')
+    clash.conflict = true
+    throw clash
+  }
+  const tmp = `${abs}.k0-tmp`
+  try {
+    fs.writeFileSync(tmp, text, { mode: s.mode & 0o777 })
+    fs.renameSync(tmp, abs)
+  } catch (e) {
+    fs.rmSync(tmp, { force: true })
+    throw e
+  }
+  const now = fs.statSync(abs)
+  return { size: now.size, mtime: Math.floor(now.mtimeMs) }
+}
+
 /** Show it in the file manager: the only way to open what cannot be shown here. */
 export const reveal = (abs) => shell.revealInFileManager(abs)
+
+/** A folder is opened rather than pointed at: what you want is to be inside it. */
+export const openFolder = (abs) => shell.openInFileManager(abs)

package/server/idle.js

@@ -0,0 +1,56 @@
+/**
+ * Which terminals have been sitting there long enough to be worth giving back.
+ *
+ * A session left open costs memory whether or not anybody is looking at it: the `claude` process,
+ * the MCP servers it started, the browsers those opened. `Close` on a card has always been the
+ * cure — it stops the session and shuts its window, leaves the card exactly where it is, and
+ * `Resume` picks the conversation up where it was. This is that same gesture, remembered for you.
+ *
+ * Only the deciding lives here. Nothing in this file kills anything, opens anything or reads a
+ * disk, which is what lets every rule below be proved without a machine to prove it on.
+ */
+
+const HOUR = 3600000
+
+/**
+ * The cards whose terminal should go, most of the rules being about what to leave alone.
+ *
+ * Yellow only — `IDLE`, the ball in your court. Not because the others are less forgotten but
+ * because of what closing them would destroy: a question and a finished plan are drawn by the
+ * terminal and are not in the transcript yet, so shutting that window throws away the very thing
+ * it was showing you. `WORKING` and `PLANNING` are somebody mid-thought. And a session Claude
+ * Code reports as `shell` is a shell you dropped into, which may well have a command of yours
+ * running in it — k0 does not know what, so k0 does not touch it.
+ */
+export function dueForClose({ cards, live, hours, now = Date.now() }) {
+  if (!(hours > 0)) return [] // switched off, and nothing to think about
+  const deadline = now - hours * HOUR
+  return cards.filter((card) => {
+    if (card.completed_at || !card.session_id || !card.session_alive) return false
+    if (card.status !== 'IDLE') return false
+    const session = live.get(card.session_id)
+    if (!session || session.status !== 'idle') return false
+    return lastSignOfLife(card, session) <= deadline
+  })
+}
+
+/**
+ * The most recent sign that something happened here, from every source that keeps one, and the
+ * newest of them wins.
+ *
+ * Taking the maximum is the whole safety of this feature. Being wrong in that direction leaves a
+ * window open and costs a few hundred megabytes until tomorrow; being wrong the other way closes
+ * a terminal somebody was about to go back to. So a single stale clock can never be the one that
+ * decides.
+ *
+ * `updatedAt` and `statusUpdatedAt` come out of Claude Code's own `~/.claude/sessions/<pid>.json`,
+ * which k0 already reads every second and until now threw away. They move when the session really
+ * changes state and are not a heartbeat — a session that had been busy for twenty-three minutes
+ * was carrying timestamps twenty-three minutes old — so they say what they appear to say.
+ *
+ * `updated_at` matters for the case none of the others cover: resuming a card leaves the status at
+ * `IDLE`, so no new event is written and `status_since` stays as old as it was.
+ */
+export function lastSignOfLife(card, session) {
+  return Math.max(card.updated_at || 0, card.status_since || 0, session.updatedAt || 0, session.statusUpdatedAt || 0)
+}

package/server/index.js

@@ -16,6 +16,8 @@ import {
   relayoutWindows,
 } from './launcher.js'
 import * as mode from './mode.js'
+import * as settings from './settings.js'
+import { dueForClose } from './idle.js'
 import { listProjects, onDisk, projectName } from './projects.js'
 import { scanSessions } from './sessions.js'
 import * as git from './git.js'
@@ -25,7 +27,7 @@ import * as files from './files.js'
 import * as pdf from './pdf.js'
 import * as machine from './machine.js'
 import * as servers from './servers.js'
-import { report as platformReport } from '../platform/index.js'
+import { report as platformReport, capabilities, why } from '../platform/index.js'
 // The same front-matter reader the viewer uses: the PDF has to be called what the page is
 // called, and two different readings of the same header would give two different names.
 import { matter, titleOf } from '../web/md.js'
@@ -65,7 +67,50 @@ function tick() {
   // The power levers are checked once a minute rather than every round: reading the power
   // state costs processes, and the things it has to follow — the mains plugged in or out, the
   // battery going down — do not change from one second to the next.
-  if (rounds++ % 60 === 0) mode.guard()
+  if (rounds % 60 === 0) mode.guard()
+  // The forgotten terminals, on the same cadence but half a minute off it, so the two jobs that
+  // only run once a minute never land in the same second as each other.
+  if (rounds % 60 === 30) sweepIdle(live)
+  rounds++
+}
+
+/**
+ * Gives back the memory of the windows you have stopped using.
+ *
+ * It does exactly what the `Close` link on a card does, and on purpose the same three moves and
+ * not a path of its own: stop the session, shut the window, forget the window. The card stays
+ * where it is with the status it had, `session_id` is untouched, and `Resume` picks the
+ * conversation up where it was — a closed terminal is not a lost session.
+ *
+ * Deliberately not awaited by `tick`: closing a terminal waits up to two seconds for the process
+ * to go, and the watching loop must not be held up by it. Hence the latch, the same one
+ * `machine.js` and `servers.js` keep for their own sampling — `setInterval` will happily start a
+ * second round on top of the first.
+ */
+let sweeping = false
+async function sweepIdle(live) {
+  if (sweeping) return
+  const hours = settings.read().closeIdleTerminalsAfterHours
+  const due = dueForClose({ cards: db.listCards(), live, hours })
+  if (!due.length) return
+  sweeping = true
+  try {
+    for (const card of due) {
+      try {
+        await closeTerminal({ winId: card.terminal_window_id, pid: live.get(card.session_id)?.pid })
+        db.setTerminalWindow(card.id, null) // that window is gone; Resume opens a new one
+        db.setAutoClosed(card.id, true)
+        console.log(`k0 — "${card.title}" sat still for ${hours}h: its terminal is closed, Resume picks it up`)
+      } catch (err) {
+        // One window that refuses to go must not take the others with it, and must certainly not
+        // take the server: nothing is awaiting this, so a rejection escaping here would end the
+        // process outright. It runs unattended — the next round is the retry.
+        console.error(`k0 — could not close the terminal of "${card.title}": ${String(err?.message || err)}`)
+      }
+    }
+  } finally {
+    sweeping = false
+  }
 }
 
 /** When somebody last looked at the board. */
@@ -186,6 +231,10 @@ function board() {
     mode: mode.current(),
     lid: mode.lid(),
     reason: mode.reason(),
+    // After how long a forgotten terminal is closed, so the machine chip can say that it is
+    // watching and after how long. Zero means it is switched off, and then the chip says nothing
+    // rather than saying "0h" — a number that would read as "closes immediately".
+    closeIdleAfterHours: settings.read().closeIdleTerminalsAfterHours,
     // What this machine can and cannot do, so the board greys out the rest and says why
     // instead of offering a button that quietly does nothing.
     platform: platformReport(),
@@ -292,6 +341,11 @@ function site(req, res, seg) {
 // is a much smaller loss than that, so the header is gone.
 const SANDBOX = 'sandbox'
 
+// How much a save is allowed to carry. Well under the megabyte the body reader stops at, which
+// would otherwise refuse a large file with a message about requests instead of about the file —
+// and far above anything you would actually edit in a browser tab: k0's own README is 56 KB.
+const MAX_SAVE = 1 << 18
+
 // ── The recap of a window ────────────────────────────────────────────────────
 // Held for a minute, and not as a saved result: the page asks for the facts, then asks for the
 // write-up to start, then asks every second whether it is done. Reading every repository's git
@@ -491,8 +545,11 @@ async function api(req, res, url) {
     const card = Number.isInteger(cardId) && cardId > 0 ? db.getCard(cardId) : null
     // Searching inside the files: the page asks for it as you type, and it needs neither the
     // listing nor git's state.
+    // `nerd` is the switch in the page: with it on, the configuration files are listed, so the
+    // search inside the text has to look in them too.
+    const nerd = url.searchParams.get('nerd') === '1'
     if (url.searchParams.get('only') === 'text') {
-      return send(res, 200, { hits: await files.grep(root, url.searchParams.get('q') || '') })
+      return send(res, 200, { hits: await files.grep(root, url.searchParams.get('q') || '', nerd) })
     }
     const changed = await files.changed(root, card?.head_at_start)
     if (url.searchParams.get('only') === 'changed') return send(res, 200, { changed, now: Date.now() })
@@ -505,6 +562,13 @@ async function api(req, res, url) {
       truncated: all.truncated,
       changed,
       files: all.files,
+      // What this machine can do about a file, so the viewer greys the buttons out and says why
+      // rather than offering something that would quietly do nothing.
+      can: {
+        reveal: capabilities.revealInFileManager,
+        open: capabilities.openInFileManager,
+        whyNot: why('revealInFileManager') || why('openInFileManager'),
+      },
       now: Date.now(),
     })
   }
@@ -560,10 +624,27 @@ async function api(req, res, url) {
       return res.end(out)
     }
 
+    // One button, two neighbouring things: a file is pointed at inside its folder, a folder is
+    // opened. Which of the two is decided here rather than in the page, because the page would
+    // have to guess and the disk already knows.
     if (idRaw === 'reveal' && req.method === 'POST') {
-      await files.reveal(abs)
+      if (fs.statSync(abs).isDirectory()) await files.openFolder(abs)
+      else await files.reveal(abs)
       return send(res, 200, { ok: true })
     }
+
+    // The first thing k0 writes into one of your repositories. Only configuration and notes, only
+    // a file that is already there, and only if nobody has touched it since the page read it.
+    if (idRaw === 'save' && req.method === 'POST') {
+      if (!files.isEditable(rel)) return send(res, 400, { error: 'This kind of file is not edited here' })
+      if (typeof body.text !== 'string') return send(res, 400, { error: 'Nothing to save' })
+      if (Buffer.byteLength(body.text) > MAX_SAVE) return send(res, 400, { error: 'That is too big to save from here' })
+      try {
+        return send(res, 200, files.write(abs, body.text, Number(body.mtime)))
+      } catch (e) {
+        return send(res, e.conflict ? 409 : 500, { error: e.message })
+      }
+    }
     if (!idRaw && req.method === 'GET') return send(res, 200, { path: rel, ...files.read(abs) })
   }
 
@@ -623,6 +704,7 @@ async function api(req, res, url) {
       const pid = readLiveSessions().get(card.session_id)?.pid
       const out = await closeTerminal({ winId: card.terminal_window_id, pid })
       db.setTerminalWindow(id, null) // that window is gone; Resume opens a new one
+      db.setAutoClosed(id, false) // this one was you: the card must not say otherwise
       tick() // so the answer already carries the closed card, without waiting for the loop
       return send(res, 200, { ...out, card: db.getCard(id) })
     }
@@ -642,6 +724,7 @@ async function api(req, res, url) {
       try {
         const out = await launch({ card: db.getCard(id), sessionId, mode: resuming ? 'resume' : 'start' })
         db.setTerminalWindow(id, out.winId)
+        db.setAutoClosed(id, false) // there is a window again: whoever shut the last one is history
         tick()
         return send(res, 200, { ...out, card: db.getCard(id) })
       } catch (err) {
@@ -694,6 +777,9 @@ http
     }
   })
   .listen(PORT, '127.0.0.1', () => {
+    // The settings file, written out with everything in it the first time k0 runs: it is the only
+    // list of what can be changed, so it has to exist before anybody goes looking for it.
+    settings.ensure()
     tick()
     // The mode is remembered, and at startup it puts the machine back as it was: the sleep
     // levers and, where needed, the font size of terminals left open. The server restarts often

package/server/launcher.js

@@ -105,7 +105,11 @@ export async function launch({ card, sessionId, mode = 'start' }) {
   const up = await waitForSession(sessionId)
 
   if (autoSend) return { name, up, winId, pasted: true, autoSent: true }
-  if (!up || !card.prompt?.trim()) return { name, up, winId, pasted: false }
+  // The prompt belongs to the beginning. Resuming picks up a conversation that answered it hours
+  // ago, and putting it back under the cursor is at best a stale instruction in the way — at
+  // worst it is sent, because where pasting is unavailable the fallback below types it. This
+  // matters more now that k0 closes forgotten terminals by itself: a Resume is no longer rare.
+  if (resume || !up || !card.prompt?.trim()) return { name, up, winId, pasted: false }
 
   await waitForPrompt(winId)
 

package/server/paths.js

@@ -12,10 +12,11 @@ import { fileURLToPath } from 'node:url'
  * there is on borrowed time. Data now lives in a directory owned by the user, and the
  * installed copy of the app is disposable.
  *
- *   ~/.k0/k0.db      the board
- *   ~/.k0/app/       the installed copy of k0 (written by `k0-board install`)
- *   ~/.k0/logs/      service stdout/stderr
- *   ~/.k0/cache/     pasted images, the Chrome profile used for PDF export
+ *   ~/.k0/k0.db        the board
+ *   ~/.k0/config.json  the settings, written out with everything in it on the first run
+ *   ~/.k0/app/         the installed copy of k0 (written by `k0-board install`)
+ *   ~/.k0/logs/        service stdout/stderr
+ *   ~/.k0/cache/       pasted images, the Chrome profile used for PDF export
  *
  * On Windows the same tree goes under %LOCALAPPDATA%\k0, which is the local-only,
  * not-roamed location Windows expects for this kind of state.

package/server/settings.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { HOME } from './paths.js'
+
+/**
+ * The few things about k0 you are allowed to change, and the file they live in.
+ *
+ * k0 has never had one of these, and this is deliberately not the first room of a settings
+ * panel. The board shows what changes during a working day; a number you set once and then never
+ * look at again is the opposite of that, and putting it on screen would cost the one page that
+ * has to stay readable in exchange for nothing.
+ *
+ * So it is a file, and the file IS the list: k0 writes it out with every setting already in it at
+ * its default, so that opening it is how you find out what there is to change. `k0-board doctor`
+ * prints the same thing, for anyone who would rather ask than look.
+ *
+ * It lives beside the database and not inside the app, because the app directory is disposable —
+ * `npx` unpacks into a cache npm may wipe, and `k0-board install` overwrites it — and a setting
+ * an update throws away is not a setting. And it is read again whenever it changes, so editing
+ * it takes effect on the next round rather than after a restart.
+ */
+
+/** `K0_CONFIG` is how the tests stay away from the real file, the way `K0_DB` does for the board. */
+export const PATH = process.env.K0_CONFIG || path.join(HOME, 'config.json')
+
+/**
+ * Every setting there is, and what it is worth if you never touch the file. No default is written
+ * down anywhere else: this object is the whole answer to "and if I leave it alone?".
+ */
+export const DEFAULTS = {
+  closeIdleTerminalsAfterHours: 12,
+}
+
+/**
+ * The shortest timeout that is still a timeout. The sweep goes round once a minute, and a
+ * terminal you were typing into ten minutes ago is not one you have forgotten: below an hour this
+ * stops being a tidy-up and becomes a machine closing windows while you are using them. A number
+ * under it is raised rather than refused — the intent was clearly "be aggressive about it", and an
+ * hour is as aggressive as this is willing to be.
+ */
+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. ' +
+  'See Settings in the README.'
+
+/**
+ * How long a terminal may sit there. Anything that is not a number falls back to the default
+ * rather than blowing up: this arrives from a file somebody edits by hand, and from there
+ * anything can arrive. Zero and below mean off, which is how the whole thing is switched off
+ * without a second switch to be kept in step with the first.
+ */
+export function idleHours(raw) {
+  if (raw === undefined || raw === null || raw === '') return DEFAULTS.closeIdleTerminalsAfterHours
+  const n = Number(raw)
+  if (!Number.isFinite(n)) return DEFAULTS.closeIdleTerminalsAfterHours
+  if (n <= 0) return 0
+  return Math.max(MIN_HOURS, n)
+}
+
+/** 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) }
+}
+
+let cached = null
+let stamp = null // the mtime the cache was built from, or null for "there was no file"
+let broken = false
+
+/**
+ * The settings in force. The file is only re-read when its mtime moves, so this can be called
+ * from the watching loop without costing a read a second, and changing the file still lands
+ * without a restart.
+ */
+export function read() {
+  let mtime = null
+  try {
+    mtime = fs.statSync(PATH).mtimeMs
+  } catch {
+    /* no file: the defaults hold, and there is nothing to remember */
+  }
+  if (cached && stamp === mtime) return cached
+  stamp = mtime
+  if (mtime === null) broken = false // a file that is not there is not a file that is broken
+  cached = normalise(mtime === null ? null : parse())
+  return cached
+}
+
+function parse() {
+  try {
+    broken = false
+    return JSON.parse(fs.readFileSync(PATH, 'utf8'))
+  } catch {
+    // Half-saved by an editor, or one comma too many. k0 goes on with the defaults rather than
+    // refusing to start, and `doctor` is where you find out the file is being ignored — silence
+    // would be the worst of both: a setting you believe is in force and is not.
+    broken = true
+    return null
+  }
+}
+
+/**
+ * Writes the file out, with everything in it, if it is not there yet. Called explicitly at
+ * startup rather than from an import: a module that writes to your disk merely because somebody
+ * mentioned it is a module nobody can reason about.
+ */
+export function ensure() {
+  if (fs.existsSync(PATH)) return false
+  fs.mkdirSync(path.dirname(PATH), { recursive: true })
+  fs.writeFileSync(PATH, JSON.stringify({ '//': NOTE, ...DEFAULTS }, null, 2) + '\n')
+  return true
+}
+
+/** What the doctor prints: where the file is, whether it could be read, and what is in force. */
+export function status() {
+  const values = read()
+  return { path: PATH, exists: stamp !== null, broken, values }
+}

package/web/board.css

@@ -88,6 +88,10 @@ body {
   flex: none;
   background: var(--calm);
 }
+/* That k0 is looking after the memory for you is worth knowing once and then forgetting: it sits
+   on the same chip, lighter than the numbers beside it, because the numbers are what you came to
+   read and this is only there so the closing is never a surprise. */
+.gauge .idle { font-weight: 500; opacity: .6; margin-left: -2px; white-space: nowrap; }
 .gauge.warn i { background: var(--warn); }
 .gauge.bad i { background: var(--alert); }
 /* Solid red only when it is critical: the one moment it is allowed to interrupt. */
@@ -383,10 +387,18 @@ body {
   gap: 7px;
   margin-bottom: 3px;
 }
+/* The repository's name takes the room that is left, so everything after it — the git mark, the
+   memory chip — sits against the right edge of the note. The same shape as the heading of a
+   column, and for the same reason: hanging off the end of the name those marks landed in a
+   different place on every note, and a row of notes had no line to read down. */
 .postit .tag {
+  flex: 1;
   font: 500 1.05rem/1 var(--hand);
   color: rgba(0, 0, 0, .5);
   min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 /* The name is the session's: it is in monospace like the k0 mark at the top.
    Monospace is heavier at the same size, which is why it drops to .94rem. */