k0-board 0.1.0

package/platform/contract.js

@@ -0,0 +1,134 @@
+/**
+ * The line between k0 and the operating system.
+ *
+ * Everything above this file — the board, the watcher, the API — is the same on every
+ * machine. Everything below it is not: opening a terminal window is AppleScript on macOS,
+ * tmux on Linux and Windows Terminal on Windows, and none of those three agree on what a
+ * "window" even is. Rather than sprinkle `process.platform` checks through the server, all
+ * of it goes behind the small surface described here, and each platform fills it in.
+ *
+ * Two rules keep this honest.
+ *
+ * **An adapter never pretends.** If a platform cannot do something — read back what is on a
+ * terminal's screen, stop the machine sleeping when the lid closes — it says so in
+ * `capabilities` and the feature is visibly switched off in the interface. A button that
+ * quietly does nothing is worse than a button that is greyed out with a reason next to it.
+ *
+ * **Capabilities are read at runtime, not guessed from the platform name.** Whether window
+ * geometry works on Linux depends on X11 versus Wayland, not on "linux"; whether Windows can
+ * read a terminal's contents depends on whether WSL is installed. Adapters probe.
+ *
+ * @typedef {object} Capabilities
+ * @property {object} terminal
+ * @property {boolean} terminal.windows              can place, size and focus windows
+ * @property {boolean} terminal.font                 can change the font size of a live terminal
+ * @property {boolean} terminal.readScreen           can read back what is on screen
+ * @property {boolean} terminal.pasteWithoutSending  can leave a prompt sitting unsent
+ * @property {boolean} terminal.title                can rename a window from outside
+ * @property {object} power
+ * @property {boolean} power.keepAwake               can stop idle sleep
+ * @property {boolean} power.keepDisplayAwake        can stop the display sleeping
+ * @property {boolean} power.lidSleep                can stop sleep-on-lid-close
+ * @property {boolean} power.battery                 can read charge and power source
+ * @property {object} metrics
+ * @property {boolean} metrics.pressure              the kernel publishes a memory-pressure verdict
+ * @property {boolean} metrics.swap                  swap usage is readable
+ * @property {object} service
+ * @property {boolean} service.autostart             can register a service that starts at login
+ * @property {boolean} tray                          a menu bar / system tray icon is available
+ * @property {boolean} revealInFileManager
+ */
+
+/**
+ * What an adapter that can do nothing would look like. Adapters spread this and override,
+ * so a capability added here later defaults to "no" everywhere instead of crashing.
+ */
+export const NO_CAPABILITIES = {
+  terminal: { windows: false, font: false, readScreen: false, pasteWithoutSending: false, title: false },
+  power: { keepAwake: false, keepDisplayAwake: false, lidSleep: false, battery: false },
+  metrics: { pressure: false, swap: false },
+  service: { autostart: false },
+  tray: false,
+  revealInFileManager: false,
+}
+
+/**
+ * The reason a capability is missing, in a sentence the board can show to the user.
+ * Keys are dotted capability paths, e.g. `terminal.readScreen`.
+ * @typedef {Record<string, string>} CapabilityNotes
+ */
+
+/**
+ * @typedef {object} TerminalAdapter
+ * @property {(opts: {command: string, title: string}) => Promise<string|null>} open
+ *   Opens a terminal running `command` and returns an opaque handle, or null if the
+ *   platform has no notion of a handle it can address later.
+ * @property {(handle: string, title: string) => Promise<boolean>} setTitle
+ * @property {(handles: string[]) => Promise<{touched: number}>} setFont
+ *   Applies the font size the current mode asks for, leaving each window where it is.
+ * @property {(handles: string[]) => Promise<{touched: number}>} relayout
+ * @property {(handle: string) => Promise<{ok: boolean, error?: string}>} focus
+ * @property {(opts: {handle: string, pid?: number}) => Promise<{closed: boolean}>} close
+ * @property {(handle: string) => Promise<string|null>} readScreen
+ *   What is on screen right now, or null when this platform cannot look.
+ * @property {(text: string, handle: string) => Promise<{pasted: boolean, error?: string}>} paste
+ *   Puts `text` in front of the user WITHOUT submitting it.
+ * @property {(text: string, handle: string) => Promise<{written: boolean, error?: string}>} type
+ *   Writes `text` and submits it. The fallback when `paste` is unavailable.
+ * @property {() => Promise<number>} defaultFontSize
+ */
+
+/**
+ * @typedef {object} PowerAdapter
+ * @property {() => Promise<{onAcPower: boolean, charge: number|null}>} state
+ * @property {(level: null|'system'|'display') => void} inhibit
+ *   Keeps the machine awake. 'system' stops idle sleep, 'display' also keeps the screen on,
+ *   null lets everything sleep normally. Idempotent: calling it with the level already in
+ *   force does nothing.
+ * @property {() => void} release
+ * @property {(blocked: boolean) => Promise<void>} setLidSleepBlocked
+ * @property {() => Promise<boolean>} lidSleepBlocked
+ * @property {() => void} releaseSync
+ *   The last gesture on the way out, from `process.on('exit')`, where nothing async can
+ *   still start. This is what stops a machine being left awake forever.
+ */
+
+/**
+ * @typedef {object} MetricsAdapter
+ * @property {() => Promise<Map<number, {ppid: number, rss: number, cpu: number, cmd: string}>>} processes
+ * @property {() => Promise<{total: number, used: number, app: number, wired: number, compressed: number, cached: number}>} memory
+ * @property {() => Promise<{total: number, used: number}>} swap
+ * @property {() => Promise<number>} pressureLevel  1 normal, 2 warning, 4 critical
+ */
+
+/**
+ * @typedef {object} ShellAdapter
+ * @property {(absPath: string) => Promise<unknown>} revealInFileManager
+ * @property {(url: string) => Promise<unknown>} openBrowser
+ * @property {() => string|null} findChrome        a Chromium-family browser able to print
+ * @property {() => Set<string>} homeSkipList      directories under $HOME that are never projects
+ * @property {() => string} findClaude             the Claude Code binary
+ */
+
+/**
+ * @typedef {object} ServiceAdapter
+ * @property {(opts: {node: string, entry: string, port: number, logDir: string, tray?: string}) => Promise<void>} install
+ * @property {() => Promise<void>} uninstall
+ * @property {() => Promise<void>} restart
+ * @property {() => Promise<{running: boolean}>} status
+ * @property {() => {path: string, what: string}[]} describe
+ *   Everything this adapter will write, for the consent screen the installer shows before
+ *   it touches anything. If it is not in this list, the installer must not create it.
+ */
+
+/**
+ * @typedef {object} PlatformAdapter
+ * @property {string} name
+ * @property {Capabilities} capabilities
+ * @property {CapabilityNotes} notes
+ * @property {TerminalAdapter} terminal
+ * @property {PowerAdapter} power
+ * @property {MetricsAdapter} metrics
+ * @property {ShellAdapter} shell
+ * @property {ServiceAdapter} service
+ */

package/platform/darwin/extras.js

@@ -0,0 +1,254 @@
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { run, runQuiet, runSyncQuiet, which } from '../shared/run.js'
+
+/**
+ * The optional system tweaks, each one opt-in.
+ *
+ * These are the parts of installing k0 that reach outside its own files and change something
+ * about the machine. They are listed separately from the service because the installer shows
+ * them one by one and asks before touching anything: a tool that quietly writes to
+ * /etc/sudoers.d and rewrites your Terminal preferences has no business being installed with
+ * a single unexplained "y".
+ *
+ * Every extra can say whether it applies here, whether it is already in place, how to put it
+ * there, and how to take it away again.
+ */
+
+const SUDO = () => which('sudo', ['/usr/bin/sudo'])
+const PMSET = () => which('pmset', ['/usr/bin/pmset'])
+const VISUDO = () => which('visudo', ['/usr/sbin/visudo'])
+const PLUTIL = () => which('plutil', ['/usr/bin/plutil'])
+const DEFAULTS = () => which('defaults', ['/usr/bin/defaults'])
+const KILLALL = () => which('killall', ['/usr/bin/killall'])
+const SW_VERS = () => which('sw_vers', ['/usr/bin/sw_vers'])
+const PS = () => which('ps', ['/bin/ps'])
+
+// ── Staying awake with the lid closed ────────────────────────────────────────
+// `caffeinate`, the thing you run by hand in a terminal, only sets *idle* assertions: they
+// stop sleep from inactivity, not the sleep that fires when the lid closes, which is a forced
+// sleep and goes straight past them. The only thing that stops that one too is the system
+// flag `SleepDisabled`, and turning it on takes root.
+//
+// The server runs under launchd with no terminal in front of it, so nobody could type a
+// password. Which is why permission is granted here, once, for that command and nothing
+// else — no wildcards, the arguments spelled out, so the blast radius is exactly two command
+// lines.
+
+const SUDOERS = '/etc/sudoers.d/k0-pmset'
+
+const sudoersRule = () =>
+  `${os.userInfo().username} ALL=(root) NOPASSWD: /usr/bin/pmset -a disablesleep 1, /usr/bin/pmset -a disablesleep 0\n`
+
+/** Runs a command with the terminal attached, so sudo can ask for a password. */
+function interactive(file, args) {
+  return new Promise((resolve) => {
+    const child = spawn(file, args, { stdio: 'inherit' })
+    child.on('exit', (code) => resolve(code === 0))
+    child.on('error', () => resolve(false))
+  })
+}
+
+const lidSleep = {
+  id: 'lid-sleep',
+  title: 'Keep this Mac awake with the lid closed',
+  detail:
+    'Grants one administrator rule so k0 can toggle the system sleep flag. That is all it ' +
+    'can ever do as root: that command, with those arguments. Asks for your password once.',
+  target: SUDOERS,
+  supported: () => true,
+
+  /**
+   * Already fine means the rule exists AND really does grant that command without a password.
+   * The file itself cannot be read back (it is 0440 root, as it should be), but `sudo -l`
+   * answers the question that actually matters — "will you let me do this without asking?" —
+   * without running anything.
+   */
+  async installed() {
+    if (!fs.existsSync(SUDOERS)) return false
+    const out = await runQuiet(SUDO(), ['-n', '-l', PMSET(), '-a', 'disablesleep', '1'])
+    return !!out
+  },
+
+  async install() {
+    const tmp = path.join(os.tmpdir(), `k0-pmset-${process.pid}`)
+    fs.writeFileSync(tmp, sudoersRule(), { mode: 0o600 })
+    try {
+      // A malformed file in /etc/sudoers.d makes `sudo` unusable on the whole machine: it is
+      // validated BEFORE being put in place, and if it does not pass, nothing is installed.
+      await run(VISUDO(), ['-c', '-f', tmp])
+    } catch {
+      fs.unlinkSync(tmp)
+      return { ok: false, message: 'the rule did not pass visudo, so it was not installed' }
+    }
+    const ok = await interactive(SUDO(), ['install', '-m', '0440', '-o', 'root', '-g', 'wheel', tmp, SUDOERS])
+    fs.unlinkSync(tmp)
+    return ok
+      ? { ok: true }
+      : { ok: false, message: 'permission not granted — k0 will keep the Mac awake only with the lid open' }
+  },
+
+  async uninstall() {
+    // Lift the ban on sleeping first, then remove the permission to lift it: the other order
+    // would leave the Mac awake forever with no way left to fix itself.
+    await runQuiet(SUDO(), ['-n', PMSET(), '-a', 'disablesleep', '0'])
+    if (!fs.existsSync(SUDOERS)) return { ok: true }
+    const ok = await interactive(SUDO(), ['rm', '-f', SUDOERS])
+    return { ok }
+  },
+}
+
+// ── Shift+Enter inserts a newline ────────────────────────────────────────────
+// Terminal.app, up to macOS 26, does not tell Shift+Enter from Enter: the program receives
+// the same single byte, so Claude Code sends the message instead of starting a new line. We
+// teach the Terminal profile to send Esc+Enter when you press Shift+Enter: that is the
+// sequence Claude Code reads as "new line" (the same one its own /terminal-setup installs for
+// VS Code, Zed and Alacritty). From macOS 27 the Terminal does it by itself and nothing here
+// is touched.
+//
+// The when matters as much as the what: Terminal reads key bindings ONLY at startup, and on
+// quitting it rewrites its preferences from what it had in memory — erasing our entry. Writing
+// it while Terminal is running is therefore useless at best and counterproductive at worst:
+// the only moment the write survives is right after Terminal has died. The menu bar icon
+// catches that moment and calls us back (see menubar/K0MenuBar.swift).
+
+const PREFS = path.join(os.homedir(), 'Library', 'Preferences', 'com.apple.Terminal.plist')
+const BACKUP = `${PREFS}.k0.bak`
+
+/** How Terminal writes a key in a profile: modifiers first ($ = Shift), then the key code. */
+const KEY = '$000D'
+/** Esc followed by carriage return: the sequence Claude Code reads as "new line". */
+const ESC_ENTER = '\x1b\r'
+
+// plutil uses the dot as a path separator: dots inside a profile name have to be protected,
+// or a profile called "My.Profile" would split the path in two.
+const entryPath = (profile) => `Window Settings.${profile.replace(/\./g, '\\.')}.keyMapBoundKeys.${KEY}`
+const dictPath = (profile) => `Window Settings.${profile.replace(/\./g, '\\.')}.keyMapBoundKeys`
+
+/**
+ * The profiles to touch: the default one and, if different, the one Terminal opens new
+ * windows with. These are the same two reads Claude Code's /terminal-setup makes.
+ */
+async function profiles() {
+  const fallback = (await runQuiet(DEFAULTS(), ['read', 'com.apple.Terminal', 'Default Window Settings'])).trim()
+  const startup = (await runQuiet(DEFAULTS(), ['read', 'com.apple.Terminal', 'Startup Window Settings'])).trim()
+  return [...new Set([fallback, startup].filter(Boolean))]
+}
+
+const hasBinding = (profile) => !!runSyncQuiet(PLUTIL(), ['-extract', entryPath(profile), 'raw', '-o', '-', PREFS])
+
+/**
+ * pgrep is no good here: it cannot see the Terminal process's command line, and
+ * `pgrep -x Terminal` misses it because the name is the full path.
+ */
+async function terminalRunning() {
+  const out = await runQuiet(PS(), ['-Ao', 'comm='])
+  return /Terminal\.app\/Contents\/MacOS\/Terminal/.test(out)
+}
+
+async function majorVersion() {
+  const out = await runQuiet(SW_VERS(), ['-productVersion'])
+  return Number(String(out).trim().split('.')[0]) || 0
+}
+
+const shiftEnter = {
+  id: 'shift-enter',
+  title: 'Shift+Enter starts a new line in Terminal',
+  detail:
+    'Adds one key binding to your Terminal profiles, after backing the preferences up. ' +
+    'Without it, Shift+Enter sends the message instead of starting a new line.',
+  target: PREFS,
+  async supported() {
+    return (await majorVersion()) < 27
+  },
+
+  async installed() {
+    if (!fs.existsSync(PREFS)) return false
+    const list = await profiles()
+    return list.length > 0 && list.every(hasBinding)
+  },
+
+  async install() {
+    if ((await majorVersion()) >= 27) return { ok: true, message: 'macOS does this by itself now' }
+    // Nothing is written while Terminal is running: it would not read the entry anyway, and on
+    // quitting it would write its in-memory preferences over the top. The menu bar icon calls
+    // us back the moment Terminal closes.
+    if (await terminalRunning()) {
+      return { ok: false, message: 'Terminal is open — k0 will add it as soon as you quit Terminal' }
+    }
+    if (!fs.existsSync(PREFS)) return { ok: false, message: 'Terminal preferences not found' }
+
+    // Before writing, wake up cfprefsd, which caches preferences: if it is still holding
+    // anything from a Terminal that just quit, it flushes it to disk NOW. Without this it
+    // would flush after us, over the entry we just wrote — which is exactly the trap this
+    // whole story started from. Terminal is already dead here, so nothing is taken from anybody.
+    await runQuiet(KILLALL(), ['cfprefsd'])
+    await new Promise((r) => setTimeout(r, 1000))
+
+    const list = await profiles()
+    let wrote = false
+    const failed = []
+    for (const profile of list) {
+      if (hasBinding(profile)) continue
+      // A backup before writing, and only the first time: making it now would save the
+      // already-modified preferences, which is to say nothing.
+      if (!fs.existsSync(BACKUP)) await runQuiet(DEFAULTS(), ['export', 'com.apple.Terminal', BACKUP])
+      // The bindings dictionary has to be created if it is not there yet; if it is, this
+      // -insert fails, and that is correct.
+      await runQuiet(PLUTIL(), ['-insert', dictPath(profile), '-dictionary', PREFS])
+      await runQuiet(PLUTIL(), ['-insert', entryPath(profile), '-string', ESC_ENTER, PREFS])
+      if (hasBinding(profile)) wrote = true
+      else failed.push(profile)
+    }
+    // cfprefsd caches preferences: without this, nobody sees what we wrote to the file.
+    if (wrote) await runQuiet(KILLALL(), ['cfprefsd'])
+    if (failed.length) {
+      return {
+        ok: false,
+        message:
+          `could not write it to ${failed.join(', ')}. By hand: Terminal → Settings → Profiles → ` +
+          'Keyboard → "+", key Return, modifier Shift, action "Send Text" with Esc and Enter.',
+      }
+    }
+    return { ok: true }
+  },
+
+  async uninstall() {
+    if (!fs.existsSync(PREFS)) return { ok: true }
+    let removed = false
+    for (const profile of await profiles()) {
+      if (!hasBinding(profile)) continue
+      // ONLY this entry is deleted: the dictionary and any bindings added by hand stay.
+      await runQuiet(PLUTIL(), ['-remove', entryPath(profile), PREFS])
+      removed = true
+    }
+    if (removed) await runQuiet(KILLALL(), ['cfprefsd'])
+    return { ok: true, message: removed ? 'reopen Terminal for it to take effect' : undefined }
+  },
+}
+
+// ── Accessibility ────────────────────────────────────────────────────────────
+// Not something an installer can grant: macOS only lets the user do it, by hand, in System
+// Settings. It is listed anyway so the consent screen can say what is being asked for and,
+// more to the point, what it means.
+
+const accessibility = {
+  id: 'accessibility',
+  title: 'Accessibility permission, so k0 can leave a prompt unsent',
+  detail:
+    'k0 simulates a Cmd+V to place your prompt in the terminal without sending it. macOS ' +
+    'only allows that for apps you approve in System Settings → Privacy & Security → ' +
+    'Accessibility. Note that a process with this permission can send keystrokes to any ' +
+    'app. Skipping it breaks nothing: the prompt gets typed and the session starts by itself.',
+  target: 'System Settings → Privacy & Security → Accessibility',
+  supported: () => true,
+  manual: true,
+  installed: async () => false,
+  install: async () => ({ ok: false, message: 'grant this by hand in System Settings' }),
+  uninstall: async () => ({ ok: true, message: 'revoke this by hand in System Settings' }),
+}
+
+export const extras = [lidSleep, shiftEnter, accessibility]
+export { shiftEnter }

package/platform/darwin/index.js

@@ -0,0 +1,24 @@
+import * as terminal from './terminal.js'
+import * as power from './power.js'
+import * as metrics from './metrics.js'
+import * as shell from './shell.js'
+import * as service from './service.js'
+import { extras } from './extras.js'
+import { NO_CAPABILITIES } from '../contract.js'
+
+export const name = 'macOS'
+
+export const capabilities = {
+  ...NO_CAPABILITIES,
+  terminal: terminal.capabilities,
+  power: power.capabilities,
+  metrics: metrics.capabilities,
+  service: service.capabilities,
+  tray: true,
+  revealInFileManager: true,
+}
+
+/** Nothing is missing here, so there is nothing to explain. */
+export const notes = {}
+
+export { terminal, power, metrics, shell, service, extras }

package/platform/darwin/metrics.js

@@ -0,0 +1,59 @@
+import os from 'node:os'
+import { runQuiet, which } from '../shared/run.js'
+import { parsePs } from '../shared/ps.js'
+
+const OPTS = { maxBuffer: 1 << 24 }
+
+const PS = () => which('ps', ['/bin/ps'])
+const VM_STAT = () => which('vm_stat', ['/usr/bin/vm_stat'])
+const SYSCTL = () => which('sysctl', ['/usr/sbin/sysctl'])
+
+export async function processes() {
+  return parsePs(await runQuiet(PS(), ['-axo', 'pid=,ppid=,rss=,time=,command='], OPTS))
+}
+
+/**
+ * `vm_stat`, in pages. The entries that matter are the ones Activity Monitor uses to build
+ * its "memory used": anonymous pages minus purgeable ones are the applications' memory, and
+ * to those you add wired and compressed. The rest — files held in cache — is not memory
+ * anybody is short of.
+ */
+export function parseVmStat(out) {
+  const text = String(out ?? '')
+  const page = Number(/page size of (\d+)/.exec(text)?.[1]) || 4096
+  const of = (label) => Number(new RegExp(`^${label}:\\s+(\\d+)`, 'm').exec(text)?.[1] || 0) * page
+
+  const wired = of('Pages wired down')
+  const compressed = of('Pages occupied by compressor')
+  const app = Math.max(0, of('Anonymous pages') - of('Pages purgeable'))
+  return { used: app + wired + compressed, app, wired, compressed, cached: of('File-backed pages') }
+}
+
+export async function memory() {
+  return { total: os.totalmem(), ...parseVmStat(await runQuiet(VM_STAT(), [], OPTS)) }
+}
+
+/** `vm.swapusage: total = 13312.00M  used = 12660.19M  free = 651.81M` */
+export function parseSwap(out) {
+  const grab = (k) => {
+    const m = new RegExp(`${k} = ([\\d.]+)([KMG])`).exec(String(out ?? ''))
+    if (!m) return 0
+    return Number(m[1]) * { K: 1024, M: 1024 ** 2, G: 1024 ** 3 }[m[2]]
+  }
+  return { total: grab('total'), used: grab('used') }
+}
+
+export async function swap() {
+  return parseSwap(await runQuiet(SYSCTL(), ['vm.swapusage'], OPTS))
+}
+
+/**
+ * Not our verdict to invent: `kern.memorystatus_vm_pressure_level` is the kernel's own
+ * judgement — 1 normal, 2 warning, 4 critical.
+ */
+export async function pressureLevel() {
+  const out = await runQuiet(SYSCTL(), ['-n', 'kern.memorystatus_vm_pressure_level'], OPTS)
+  return Number(String(out).trim()) || 1
+}
+
+export const capabilities = { pressure: true, swap: true }

package/platform/darwin/power.js

@@ -0,0 +1,133 @@
+import { spawn } from 'node:child_process'
+import { run, runSyncQuiet, which } from '../shared/run.js'
+
+/**
+ * Keeping a Mac awake.
+ *
+ * There are two levers here, and `caffeinate` alone is not enough: its assertions are all
+ * *idle* assertions. They stop sleep from inactivity but not the sleep that fires when the
+ * lid closes, which is forced and goes straight past them. Only the system flag
+ * `SleepDisabled` stops that one, and it wants root — see the installer, which grants that
+ * one command and nothing else.
+ */
+
+const SUDO = () => which('sudo', ['/usr/bin/sudo'])
+const PMSET = () => which('pmset', ['/usr/bin/pmset'])
+const CAFFEINATE = () => which('caffeinate', ['/usr/bin/caffeinate'])
+
+/** `-i` is idle sleep, `-m` the disk, `-d` the display. The `-d` is the whole difference. */
+const FLAGS = { system: '-im', display: '-dim' }
+
+let child = null // the `caffeinate` child, when there is one
+let activeLevel = null // which level it was started with: changing mode means redoing it
+
+/**
+ * `SleepDisabled` inside the output of `pmset -g`. When it is zero the line can be missing
+ * altogether, so "I did not find it" and "it is 0" are the same answer.
+ */
+export function parseSleepDisabled(out) {
+  const m = /^\s*SleepDisabled\s+(\d+)/m.exec(String(out ?? ''))
+  return !!m && m[1] !== '0'
+}
+
+/**
+ * Where the power comes from and how much charge is left, from `pmset -g batt`. A desktop
+ * has no battery: charge comes back `null`, and no threshold should fire for it.
+ */
+export function parseBattery(out) {
+  const text = String(out ?? '')
+  const charge = /(\d+)%/.exec(text)
+  return {
+    onAcPower: !/battery power/i.test(text),
+    charge: charge ? Number(charge[1]) : null,
+  }
+}
+
+export async function state() {
+  try {
+    const stdout = await run(PMSET(), ['-g', 'batt'])
+    return parseBattery(stdout)
+  } catch {
+    // If we cannot ask, assume the case that does no harm: plugged in, no threshold to trip.
+    return { onAcPower: true, charge: null }
+  }
+}
+
+/**
+ * The `caffeinate` for this level. Changing mode changes the flags, and a running process
+ * cannot have its flags changed: it gets killed and remade. The `-w <our pid>` is the first
+ * safety net — it stops by itself when the server dies, even if the server is killed
+ * outright and never gets to switch anything off.
+ */
+export function inhibit(level) {
+  if (child && activeLevel === level) return
+  release()
+  if (!level) return
+  const flag = FLAGS[level]
+  if (!flag) return
+  const spawned = spawn(CAFFEINATE(), [flag, '-w', String(process.pid)], { stdio: 'ignore' })
+  child = spawned
+  activeLevel = level
+  // Comparing against `spawned` is not pedantry: the `exit` of the KILLED process arrives
+  // AFTER the new one has already started, and a handler that blindly cleared `child` would
+  // wipe out the reference to the new one. On the next pass k0 would believe it had none and
+  // start a second — measured: two live `caffeinate` processes, one of them with nobody left
+  // who knows about it.
+  const forget = () => {
+    if (child !== spawned) return
+    child = null
+    activeLevel = null
+  }
+  spawned.on('error', forget)
+  spawned.on('exit', forget)
+  spawned.unref() // it is not its job to keep the server alive
+}
+
+export function release() {
+  activeLevel = null
+  if (!child) return
+  try {
+    child.kill()
+  } catch {
+    /* already gone on its own */
+  }
+  child = null
+}
+
+/**
+ * `sudo -n`: the `-n` is the part that matters. Without the rule in /etc/sudoers.d the
+ * command fails IMMEDIATELY instead of hanging waiting for a password nobody here can type —
+ * the server runs under launchd, with no terminal in front of it.
+ */
+export async function setLidSleepBlocked(blocked) {
+  try {
+    await run(SUDO(), ['-n', PMSET(), '-a', 'disablesleep', blocked ? '1' : '0'])
+  } catch {
+    /* no sudo rule: carry on with caffeinate alone */
+  }
+}
+
+export async function lidSleepBlocked() {
+  try {
+    return parseSleepDisabled(await run(PMSET(), ['-g']))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The last gesture on the way out. Synchronous on purpose: from `process.on('exit')` nothing
+ * asynchronous gets to start any more, and this is the net that stops a Mac being left awake
+ * forever because k0 went away while it was on.
+ */
+export function releaseSync() {
+  release()
+  runSyncQuiet(SUDO(), ['-n', PMSET(), '-a', 'disablesleep', '0'], { stdio: 'ignore', timeout: 4000 })
+}
+
+export const capabilities = {
+  keepAwake: true,
+  keepDisplayAwake: true,
+  lidSleep: true,
+  battery: true,
+}