@ucsandman/legcli 0.10.0 → 0.11.0

package/src/board/audit.js

@@ -0,0 +1,123 @@
+// Audit trail: who did what, across every terminal and every card on this
+// board. Data: /api/audit, which is owner-only — the trail names repositories
+// and the people on the roster.
+//
+// It loads when the reader asks, never on a board render: the trail reads every
+// session's events and every card's ledger, and that is not work to do on a
+// timer behind a panel nobody has opened. Like the history cell, nothing here
+// arrives over SSE (DESIGN.md rule 3: the live terminals lane is the only live
+// region).
+//
+// `el`, `api`, `getToken`, `ago` and `whenAgo` are copied from sessions.js,
+// which cannot export from its IIFE. The time grammar is sessions.js's: a
+// change to ago() there is a change here in the same commit.
+(function () {
+  'use strict'
+
+  function getToken() { return localStorage.getItem('legToken') || localStorage.getItem('batonToken') || '' }
+  async function api(path, opts = {}) {
+    const headers = { 'Content-Type': 'application/json' }
+    const token = getToken()
+    if (token) headers.Authorization = `Bearer ${token}`
+    const r = await fetch(path, { method: opts.method || 'GET', headers, body: opts.body ? JSON.stringify(opts.body) : undefined })
+    const data = await r.json().catch(() => ({}))
+    if (!r.ok) throw new Error(data.error || `${r.status} ${r.statusText}`)
+    return data
+  }
+  function el(tag, attrs, children) {
+    const n = document.createElement(tag)
+    for (const [k, v] of Object.entries(attrs || {})) { if (v === null || v === undefined) continue; if (k === 'class') n.className = v; else n.setAttribute(k, v) }
+    for (const c of children || []) { if (c === null || c === undefined) continue; n.appendChild(typeof c === 'string' ? document.createTextNode(c) : c) }
+    return n
+  }
+  function ago(ms) {
+    const s = Math.max(0, Math.floor(ms / 1000))
+    if (s < 60) return `${s}s`
+    const m = Math.floor(s / 60)
+    if (m < 60) return `${m}m`
+    const h = Math.floor(m / 60)
+    if (h < 48) return `${h}h${m % 60 ? ` ${m % 60}m` : ''}`
+    const d = Math.floor(h / 24)
+    return `${d}d${h % 24 ? ` ${h % 24}h` : ''}`
+  }
+  function whenAgo(ts) {
+    const t = Date.parse(ts)
+    return Number.isFinite(t) ? `${ago(Date.now() - t)} ago` : ''
+  }
+  function clockAt(ms) {
+    const d = new Date(ms)
+    if (!Number.isFinite(d.getTime())) return ''
+    return d.toLocaleString(undefined, { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit', hour12: false })
+  }
+
+  const root = document.getElementById('audit')
+  if (!root) return
+  const whoSel = document.getElementById('audit-who')
+  const kindSel = document.getElementById('audit-kind')
+  const loadBtn = document.getElementById('audit-load')
+  const meta = document.getElementById('audit-meta')
+  const list = document.getElementById('audit-list')
+  let knownPeople = null
+
+  // A guest or an operator never sees this panel; the fieldset stays hidden
+  // until /api/audit answers, so a 403 leaves nothing on the page to click.
+  async function reveal() {
+    try {
+      const r = await api('/api/audit?limit=1')
+      root.hidden = false
+      knownPeople = r.people || []
+      fillPeople()
+    } catch { root.hidden = true }
+  }
+
+  function fillPeople() {
+    if (!knownPeople) return
+    const current = whoSel.value
+    while (whoSel.options.length > 1) whoSel.remove(1)
+    for (const p of knownPeople) whoSel.appendChild(el('option', { value: p }, [p]))
+    whoSel.value = current
+  }
+
+  function row(e) {
+    const line = el('div', { class: 'audit-row' })
+    line.appendChild(el('span', { class: 'audit-when', title: e.at }, [clockAt(Date.parse(e.at))]))
+    line.appendChild(el('span', { class: `chip chip-id-${e.kind === 'human' ? 'human' : (e.agent || 'leg')}` }, [e.who]))
+    line.appendChild(el('span', { class: 'audit-what' }, [e.what.replace(/_/g, ' ')]))
+    line.appendChild(el('span', { class: 'audit-summary' }, [e.summary || '']))
+    const where = e.where === 'card' ? `card ${e.id}` : `terminal ${String(e.id).split('-').pop()}`
+    line.appendChild(el('span', { class: 'chip' }, [where]))
+    if (e.repo) line.appendChild(el('span', { class: 'chip' }, [String(e.repo).split(/[\\/]/).pop() + (e.branch ? `@${e.branch}` : '')]))
+    line.appendChild(el('span', { class: 'audit-ago' }, [whenAgo(e.at)]))
+    return line
+  }
+
+  async function load() {
+    loadBtn.disabled = true
+    meta.textContent = 'reading every terminal and every card…'
+    list.replaceChildren()
+    try {
+      const q = new URLSearchParams({ limit: '200' })
+      if (whoSel.value) q.set('who', whoSel.value)
+      if (kindSel.value) q.set('kind', kindSel.value)
+      const r = await api(`/api/audit?${q}`)
+      knownPeople = r.people || knownPeople
+      fillPeople()
+      // L2: the verdict carries the volume it processed, so an empty trail from
+      // a board that looked at nothing does not read like a quiet week.
+      const scanned = `${r.scanned.sessions} terminal${r.scanned.sessions === 1 ? '' : 's'} and ${r.scanned.cards} card${r.scanned.cards === 1 ? '' : 's'}, ${r.scanned.events} events read`
+      meta.textContent = r.entries.length
+        ? `${r.matched} action${r.matched === 1 ? '' : 's'}${r.truncated ? `, newest ${r.entries.length} shown` : ''} — ${scanned}`
+        : `nothing matched — ${scanned}`
+      for (const e of r.entries) list.appendChild(row(e))
+    } catch (err) {
+      meta.textContent = err.message
+    } finally {
+      loadBtn.disabled = false
+    }
+  }
+
+  loadBtn.addEventListener('click', load)
+  whoSel.addEventListener('change', load)
+  kindSel.addEventListener('change', load)
+  reveal()
+})()

package/src/board/board.css

@@ -391,6 +391,21 @@ code { font-family: var(--mono); font-size: 0.94em; }
 .history-filters { display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 10px 14px; align-items: center; margin: 4px 0 18px; max-width: 64ch; }
 .history-filters label { font-size: var(--t-0); font-weight: var(--w-head); color: var(--text-2); }
 .history-filters label:has(input[type="checkbox"]) { grid-column: 1 / -1; display: flex; align-items: center; gap: 8px; font-weight: var(--w-text); }
+/* Audit trail (Settings). Same grammar as the history rows: a flat list with
+   hairline separators, the time on the left, the actor as a chip. */
+.audit { border: 0; padding: 0; margin: 22px 0 0; }
+.audit legend { font-size: var(--t-0); font-weight: var(--w-head); color: var(--text-2); padding: 0; }
+.audit-filters { display: flex; flex-wrap: wrap; gap: 10px 14px; align-items: center; margin: 10px 0 14px; }
+.audit-filters label { font-size: var(--t-0); font-weight: var(--w-head); color: var(--text-2); }
+.audit-list { display: block; }
+.audit-row { display: flex; flex-wrap: wrap; gap: 6px 10px; align-items: baseline; padding: 10px 0; font-size: var(--t-0); }
+.audit-row + .audit-row { border-top: 1px solid var(--line); }
+.audit-when { color: var(--text-3); font-variant-numeric: tabular-nums; min-width: 12ch; }
+.audit-what { font-weight: var(--w-head); }
+.audit-summary { color: var(--text-2); flex: 1 1 46ch; min-width: 0; overflow-wrap: anywhere; }
+.audit-ago { color: var(--text-3); margin-left: auto; }
+@media (max-width: 640px) { .audit-ago { margin-left: 0; } }
+
 .history-list { display: block; }
 .history-row { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 6px 20px; align-items: baseline; padding: 12px 0; font-size: var(--t-0); }
 .history-row + .history-row, .history-row + .history-detail, .history-detail + .history-row { border-top: 1px solid var(--line); }

package/src/board/index.html

@@ -158,6 +158,27 @@
         <button type="button" class="btn btn-secondary" id="default-order-save">Save default</button>
         <span class="field-status" id="default-order-status" aria-live="polite"></span>
       </fieldset>
+      <!-- Who did what, across every terminal and every card. The owner's, like
+           the rest of this panel: the trail names repositories and people. It
+           loads when asked rather than on every board render. -->
+      <fieldset class="audit" id="audit" hidden>
+        <legend>Audit trail</legend>
+        <p class="field-help">Every hand-off, landing, approval, reassignment and kill on this board, newest first, with the person or the agent that did it.</p>
+        <div class="audit-filters">
+          <label for="audit-who">Who</label>
+          <select id="audit-who"><option value="">anyone</option></select>
+          <label for="audit-kind">Kind</label>
+          <select id="audit-kind">
+            <option value="">people and agents</option>
+            <option value="human">people</option>
+            <option value="agent">agents</option>
+            <option value="leg">Leg itself</option>
+          </select>
+          <button type="button" class="btn btn-secondary" id="audit-load">Load</button>
+        </div>
+        <p class="region-meta" id="audit-meta" role="status" aria-atomic="true"></p>
+        <div class="audit-list" id="audit-list"></div>
+      </fieldset>
       <div class="field board-facts"></div>
     </div>
   </section>
@@ -280,5 +301,6 @@
 <script src="board.js" defer></script>
 <script src="sessions.js" defer></script>
 <script src="history.js" defer></script>
+<script src="audit.js" defer></script>
 </body>
 </html>

package/src/board/sessions.js

@@ -661,7 +661,7 @@
         sysMessage('removed the Leg record; the worktree and the branch are kept', 'ok')
       } else {
         await api(`/api/sessions/${encodeURIComponent(id)}/${action}`, { method: 'POST', body })
-        if (action === 'handoff') actionNotes.set(id, { at: Date.now(), tone: 'warn', text: 'hand-off requested; this terminal switches agents in a few seconds' })
+        if (action === 'handoff') actionNotes.set(id, { at: Date.now(), tone: 'warn', text: body && body.agent ? `hand-off to ${optionLabel(body)} requested; this terminal switches agents in a few seconds` : 'hand-off requested; this terminal switches agents in a few seconds' })
         else if (action === 'end') actionNotes.set(id, { at: Date.now(), tone: 'warn', text: 'end requested; the agent stops after its current turn' })
         else if (action === 'land/fix') actionNotes.set(id, { at: Date.now(), tone: 'ok', text: 'applied fix' })
       }
@@ -693,6 +693,34 @@
     else wrap.appendChild(el('p', { class: 'sentence tone-muted' }, [`first eligible now: ${eligible}`]))
     wrap.appendChild(el('p', { class: 'blocker' }, ['Used after a usage limit or Hand off now. A normal exit ends this terminal.']))
 
+    // The picker. The Hand off now button on the panel stays the one-click
+    // path (it takes the order); this names a destination instead. An option
+    // that cannot be picked carries the reason in its own label, so nothing is
+    // greyed out without saying why.
+    const targets = Array.isArray(s.handoff_targets) ? s.handoff_targets : []
+    if (s.active && targets.length) {
+      const pick = el('div', { class: 'form-row' })
+      const selectId = `handoff-to-${s.session_id}`
+      pick.appendChild(el('label', { for: selectId }, ['Hand off now to']))
+      const select = el('select', { id: selectId })
+      select.appendChild(el('option', { value: '' }, ['the next option in the order']))
+      targets.forEach((t, i) => {
+        const note = t.available ? '' : ` — ${t.reason}${Number.isFinite(t.resets_at) ? `, back ${until(t.resets_at)}` : ''}`
+        // the index is the value: an account name is not ours to parse
+        select.appendChild(el('option', { value: String(i), disabled: t.available ? null : 'disabled' }, [optionLabel(t) + note]))
+      })
+      const go = el('button', { type: 'button', class: 'btn btn-secondary' }, ['Hand off'])
+      go.addEventListener('click', () => {
+        const t = select.value === '' ? null : targets[Number(select.value)]
+        act(s.session_id, 'handoff', go, t ? { agent: t.agent, account: t.account } : null)
+      })
+      pick.appendChild(el('div', { class: 'chain-rail' }, [select, go]))
+      if (!targets.some((t) => t.available)) {
+        pick.appendChild(el('p', { class: 'field-help' }, ['Every destination is at its limit or not installed; a hand-off now waits for the first reset.']))
+      }
+      wrap.appendChild(pick)
+    }
+
     const editableNow = ['starting', 'running', 'warning', 'limit', 'waiting'].includes(s.status)
     if (!s.hidden && editableNow) {
       let state = sessionEditors.get(s.session_id)

package/src/server.mjs

@@ -5,12 +5,14 @@
 // LEG_BIND (127.0.0.1) + LEG_PORT (4747) + LEG_TOKEN are the
 // multiplayer seams (src/auth.mjs). BATON_* names still work as fallback.
 import http from 'node:http'
+import https from 'node:https'
 import { spawnSync, execFile } from 'node:child_process'
 import { existsSync, readFileSync, readdirSync, statSync, rmSync, watch as fsWatch, mkdirSync, openSync, fstatSync, readSync, closeSync } from 'node:fs'
 import { join, dirname, resolve, extname, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { checkBind, authorize, remoteAddress, presentedToken, isLoopback, isLoopbackRequest, tokenMatches } from './auth.mjs'
-import { readShare, isOn as shareIsOn, sharePath, identify, personNamed } from './share.mjs'
+import { readShare, isOn as shareIsOn, sharePath, identify, personNamed, mayUseCards, mayUseMachine, readTls } from './share.mjs'
+import { auditTrail, ACTOR_KINDS } from './audit.mjs'
 import { createLimiter } from './ratelimit.mjs'
 import { realPath, canonPath } from './fsx.mjs'
 import { listCards, readCard, readRuns, readEvents, cardDir, home } from './store.mjs'
@@ -29,7 +31,7 @@ import { sessionDetail, sessionDiff, DiffInputError } from './session-detail.mjs
 import { hasRecentSynthesis } from './synthesis.mjs'
 import { refreshPointers } from './resume.mjs'
 import { landSession, landBlocker, landingNow, pruneSessionWorktree, canLand, prepareLanding, applyLandFix } from './land.mjs'
-import { readUsage, recordUsage, usageIsStale, candidates, isAvailable } from './usage.mjs'
+import { readUsage, recordUsage, usageIsStale, candidates, isAvailable, fmtReset } from './usage.mjs'
 import { readAccounts, envFor, LAYOUT } from './accounts.mjs'
 import { readCodexUsage } from './taps/codex.mjs'
 import { readPreferences, writePreferences, normalizeHandoffOrder, requireHandoffOrder } from './preferences.mjs'
@@ -343,6 +345,11 @@ function visibleSessionFile(file) {
 
 export function sessionsView({ viewer = null, share = null } = {}) {
   const shared = Boolean(share && shareIsOn(share))
+  // Decided before the map below, because the per-session payload has to know
+  // it: a guest owns their own terminal and may hand it off, so they get its
+  // list of destinations — but a reset time is this machine's usage data and
+  // belongs to nobody else, even on a terminal that is theirs.
+  const guest = shared && viewer && viewer.role !== 'owner'
   const list = reapLost(listSessions())
   const ov = overlaps(list)
   const configuredAccounts = readAccounts()
@@ -360,6 +367,21 @@ export function sessionsView({ viewer = null, share = null } = {}) {
       chain,
       preferred_next: preferredNext,
       eligible_next: eligibleNext,
+      // every destination this terminal could be handed to, each with the
+      // reason it cannot be picked right now. The board's picker renders this
+      // list directly, so a greyed option always carries its own explanation.
+      handoff_targets: chain.map((c) => {
+        const u = readUsage(c.agent, c.account)
+        const missing = availabilityKnown && s.installed[c.agent] === false
+        const walled = !isAvailable(u)
+        return {
+          agent: c.agent,
+          account: c.account,
+          available: !missing && !walled,
+          reason: missing ? 'not installed on this machine' : walled ? 'at its usage limit' : null,
+          resets_at: walled && !guest ? (u.limited_until ?? null) : null,
+        }
+      }),
       handoff_availability_known: availabilityKnown,
       can_edit_handoff_order: s.runtime_capabilities?.includes(HANDOFF_ORDER_CAPABILITY) ?? false,
       active: isActive(s),
@@ -387,7 +409,6 @@ export function sessionsView({ viewer = null, share = null } = {}) {
   const canon = new Map()
   const landingsFor = (key) => landings.filter((l) => { if (!canon.has(l.repo)) canon.set(l.repo, canonPath(l.repo)); return canon.get(l.repo) === key })
   const trunk = [...repos].map(([key, r]) => { try { return withLandings(trunkFor(r), landingsFor(key)) } catch { return { repo: r, commits: [] } } })
-  const guest = shared && viewer && viewer.role !== 'owner'
   const mine = (s) => !shared || !viewer || viewer.role === 'owner' || (s.owner ?? share.owner) === viewer.name
   const shown = sessions.map((s) => (mine(s) ? { ...s, requests: readRequests(s.session_id).filter((r) => r.state === 'pending') } : redactSession(s)))
   return {
@@ -461,14 +482,15 @@ function createSse({ healthIntervalMs = 10000, debounceMs = 30, sessionsDebounce
   // resets the count the first is reading from.
   const refreshCard = (id) => {
     const card = readCard(id)
-    // pipeline cards and their events are the owner's: a guest never gets them
-    const forOwner = (payload) => (viewer) => (viewer && viewer.role !== 'owner' ? null : payload)
+    // pipeline cards and their events belong to the people who may run them:
+    // the owner and any operator. A guest never gets them.
+    const forOwner = (payload) => (viewer) => (viewer && !mayUseCards(viewer.role) ? null : payload)
     if (!card) { for (const c of clients) c.sig.delete(id); broadcast('removed', forOwner({ card_id: id })); return }
     const events = readEvents(id)
     // broadcast() refreshes each client's viewer (and drops revoked ones) first
     broadcast('card', forOwner(summarize(card)))
     for (const c of [...clients]) {
-      if (!c.viewer || c.viewer.role !== 'owner') { c.sig.set(id, events.length); continue }
+      if (!c.viewer || !mayUseCards(c.viewer.role)) { c.sig.set(id, events.length); continue }
       const from = c.sig.get(id) ?? 0
       c.sig.set(id, events.length)
       for (const e of events.slice(from)) { try { c.res.write(`event: event\ndata: ${JSON.stringify(e)}\n\n`) } catch {} }
@@ -613,7 +635,7 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
   }
   const limiter = createLimiter()
   const viewFor = (viewer, sh) => sessionsView({ viewer, share: sh ?? currentShare() })
-  const forOwner = (payload) => (viewer) => (viewer && viewer.role !== 'owner' ? null : payload)
+  const forOwner = (payload) => (viewer) => (viewer && !mayUseCards(viewer.role) ? null : payload)
   // SSE re-identifies each client from the live roster on every push
   const reauthClient = (c) => {
     const sh = currentShare()
@@ -688,19 +710,23 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
     const rl = limiter.request(auth.person ? viewer.name : ip)
     if (!rl.ok) return send(res, 429, { error: `rate limit: more than ${limiter.max} requests a minute` }, { 'Retry-After': String(rl.retry_after) })
     const actor = { type: 'human', id: viewer.name }
-    // a guest sees the terminals lane, read-only; the pipeline side is the owner's
-    const guest = shared && viewer.role !== 'owner'
+    // What this viewer may reach, decided once from their role (src/share.mjs).
+    // `canCards` is the pipeline board: cards, the floor, the adapters and the
+    // leases, which an operator runs. `canMachine` is everything that describes
+    // this computer rather than the work — the settings, the trunk's repo
+    // paths, the history index, the worktree map — and stays the owner's.
+    const canCards = !shared || mayUseCards(viewer.role)
+    const canMachine = !shared || mayUseMachine(viewer.role)
     const ownsSession = (s) => !shared || viewer.role === 'owner' || (s.owner ?? share.owner) === viewer.name
     const parts = path.split('/').filter(Boolean) // ['api', ...]
-    // history and worktrees are the whole machine's project map (every path,
-    // every conversation on it): the owner's, never a guest's, as a group
-    if (guest && ['cards', 'floor', 'presets', 'adapters', 'leases', 'trunk', 'history', 'worktrees'].includes(parts[1])) return send(res, 403, { error: 'the pipeline board belongs to the owner of this machine' })
+    if (!canCards && ['cards', 'floor', 'presets', 'adapters', 'leases'].includes(parts[1])) return send(res, 403, { error: 'the pipeline board belongs to the owner and the operators of this machine' })
+    if (!canMachine && ['trunk', 'history', 'worktrees', 'audit'].includes(parts[1])) return send(res, 403, { error: 'this is the map of the machine itself: every repository path and every conversation on it. It belongs to the owner of this machine.' })
     try {
       if (req.method === 'GET' && path === '/api/health') {
         const you = { ...viewer, share: { on: shared, people: shared ? share.people.length : 0 } }
-        if (guest) return send(res, 200, { ok: true, version: VERSION, you })
+        if (!canCards) return send(res, 200, { ok: true, version: VERSION, you })
         const cards = listCards()
-        return send(res, 200, { ok: true, pid: process.pid, version: VERSION, bind, port, home: home(), you, scheduler: { ...schedulerStatus(), in_process: Boolean(sched), max_concurrent: MAX_CONCURRENT }, tools: await detectTools(), columns: columnsFor(cards), cards: cards.length })
+        return send(res, 200, { ok: true, pid: process.pid, version: VERSION, bind, port, home: canMachine ? home() : null, you, scheduler: { ...schedulerStatus(), in_process: Boolean(sched), max_concurrent: MAX_CONCURRENT }, tools: await detectTools(), columns: columnsFor(cards), cards: cards.length })
       }
       if (req.method === 'GET' && path === '/api/adapters') return send(res, 200, { adapters: await adaptersInfo() })
       if (req.method === 'GET' && path === '/api/presets') return send(res, 200, { presets: PRESETS })
@@ -721,14 +747,14 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
       }
       if (req.method === 'GET' && path === '/api/events') {
         res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive', 'X-Accel-Buffering': 'no' })
-        const cards = guest ? [] : listCards()
+        const cards = canCards ? listCards() : []
         res.write(`event: hello\ndata: ${JSON.stringify({ columns: columnsFor(cards), cards: cards.map(summarize), sessions: viewFor(viewer), ts: new Date().toISOString() })}\n\n`)
         sse.add(res, cards, viewer, { token: presentedToken(req, url), loopback: isLoopbackRequest(req) })
         return
       }
       if (req.method === 'GET' && path === '/api/sessions') return send(res, 200, viewFor(viewer))
       if (path === '/api/settings') {
-        if (guest) return send(res, 403, { error: 'the machine settings belong to the owner of this board' })
+        if (!canMachine) return send(res, 403, { error: 'the machine settings belong to the owner of this board' })
         if (req.method === 'GET') return send(res, 200, { preferences: readPreferences() })
         if (req.method === 'POST' || req.method === 'PATCH') {
           const body = await readBody(req)
@@ -865,9 +891,30 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
         }
         if (req.method === 'POST' && (parts[3] === 'handoff' || parts[3] === 'end')) {
           if (!isActive(sess)) return send(res, 409, { error: `session ${id} is not active` })
-          requestControl(id, parts[3] === 'handoff' ? { handoff: true, by: actor.id } : { end: true, by: actor.id })
-          log(`${parts[3]} requested for ${id} by ${actor.id}`)
-          return send(res, 200, { ok: true, requested: parts[3] })
+          if (parts[3] === 'end') {
+            requestControl(id, { end: true, by: actor.id })
+            log(`end requested for ${id} by ${actor.id}`)
+            return send(res, 200, { ok: true, requested: 'end' })
+          }
+          // Hand off now, optionally to a named destination. With no body the
+          // chain decides, exactly as it did before the picker existed.
+          const body = await readBody(req)
+          let target = null
+          if (body && body.agent !== undefined && body.agent !== null && body.agent !== '') {
+            const want = { agent: String(body.agent), account: String(body.account ?? 'default') }
+            const order = normalizeHandoffOrder(sess.handoff_order)
+            const chain = candidates({ agent: sess.agent, account: sess.account, accounts: readAccounts(), order })
+            const hit = chain.find((c) => c.agent === want.agent && c.account === want.account)
+            const label = `${want.agent}${want.account !== 'default' ? '/' + want.account : ''}`
+            if (!hit) return send(res, 400, { error: `${label} is not a destination for this terminal (${chain.map((c) => c.agent + (c.account !== 'default' ? '/' + c.account : '')).join(', ') || 'none'})` })
+            if (sess.installed && sess.installed[want.agent] === false) return send(res, 409, { error: `${label} is not installed on this machine` })
+            const u = readUsage(want.agent, want.account)
+            if (!isAvailable(u)) return send(res, 409, { error: `${label} is at its usage limit until ${fmtReset(u.limited_until)}; pick another or use Hand off now without a destination` })
+            target = hit
+          }
+          requestControl(id, target ? { handoff: true, target, by: actor.id } : { handoff: true, by: actor.id })
+          log(`handoff requested for ${id} by ${actor.id}${target ? ` to ${target.agent}/${target.account}` : ''}`)
+          return send(res, 200, { ok: true, requested: 'handoff', target })
         }
         if (req.method === 'DELETE' && parts.length === 3) {
           if (isActive(sess)) return send(res, 409, { error: 'end the session before removing it' })
@@ -944,6 +991,18 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
         const q = url.searchParams
         return send(res, 200, worktreesFor({ repo: q.get('repo') || null, dirty: q.get('dirty') !== '0' }))
       }
+      if (req.method === 'GET' && path === '/api/audit') {
+        const q = url.searchParams
+        const kind = q.get('kind')
+        if (kind && !ACTOR_KINDS.includes(kind)) return send(res, 400, { error: `kind is one of ${ACTOR_KINDS.join(', ')}` })
+        const limit = parseInt(q.get('limit') ?? '200', 10)
+        return send(res, 200, auditTrail({
+          limit: Number.isFinite(limit) ? limit : 200,
+          since: q.get('since'),
+          who: q.get('who'),
+          kind,
+        }))
+      }
       if (req.method === 'GET' && path === '/api/floor') return send(res, 200, floor(listCards()))
       if (req.method === 'GET' && path === '/api/trunk') return send(res, 200, trunk(listCards(), parseSince(url.searchParams.get('since'))))
       if (req.method === 'GET' && path === '/api/leases') return send(res, 200, { leases: held(listCards()) })
@@ -1004,21 +1063,28 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
   }
 
   const onReq = (req, res) => { handle(req, res).catch((err) => { try { send(res, 500, { error: scrub(err.message) }) } catch {} }) }
-  const server = http.createServer(onReq)
+  // TLS when a certificate pair is configured (leg share on --tls-cert/--tls-key,
+  // or LEG_TLS_CERT/LEG_TLS_KEY). readTls throws rather than fall back to
+  // plaintext: a board told to use TLS and quietly serving http would be the
+  // worst outcome of the three.
+  const tls = readTls(initialShare)
+  const server = tls ? https.createServer({ cert: tls.cert, key: tls.key }, onReq) : http.createServer(onReq)
   // When the board is bound to a non-loopback address (share on), also listen on
   // 127.0.0.1 so the machine's own browser has a tokenless owner URL — a real
-  // remote peer's address is never loopback, so it still needs a token.
+  // remote peer's address is never loopback, so it still needs a token. That one
+  // stays plain http even under TLS: the certificate is for the shared name, and
+  // loopback traffic never leaves this machine.
   const loopbackCompanion = !isLoopback(bind) ? http.createServer(onReq) : null
 
   return {
     server,
-    bind, port,
+    bind, port, tls: tls ? { cert_path: tls.cert_path, key_path: tls.key_path } : null,
     start() {
       return new Promise((resolvePromise, reject) => {
         server.once('error', reject)
         server.listen(port, bind, () => {
           const addr = server.address()
-          log(`listening on http://${bind}:${addr.port} (home ${home()}${token ? ', token required' : ', loopback open'})`)
+          log(`listening on ${tls ? 'https' : 'http'}://${bind}:${addr.port} (home ${home()}${token ? ', token required' : ', loopback open'}${tls ? `, TLS from ${tls.cert_path}` : ''})`)
           // A terminal that crashed instead of exiting left its hand-off in
           // .leg/RESUME.md looking live. The board is the thing that starts
           // after a crash, so it is where that gets corrected.

package/src/share.mjs

@@ -6,15 +6,29 @@
 // (`BATON_PERSON`, else the owner). With it off nothing changes: loopback is
 // open and `BATON_TOKEN` is the only token.
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
-import { existsSync, readFileSync, mkdirSync } from 'node:fs'
+import { existsSync, readFileSync, mkdirSync, statSync } from 'node:fs'
 import { networkInterfaces, userInfo } from 'node:os'
 import { createSocket } from 'node:dgram'
 import { join } from 'node:path'
 import { home } from './store.mjs'
 import { writeJsonAtomic } from './fsx.mjs'
 
-export const OFF = { version: 1, on: false, bind: null, bind_kind: null, port: null, owner: null, people: [] }
-export const ROLES = ['owner', 'guest']
+export const OFF = { version: 1, on: false, bind: null, bind_kind: null, port: null, owner: null, people: [], tls: null }
+
+// Three roles, because two were not enough to describe a second human who runs
+// cards on this machine but has no business in its settings or its project map.
+//   owner     everything: machine settings, the harness, every terminal, cards
+//   operator  the pipeline board and their own terminals; not the settings,
+//             not the history index, not anyone else's terminal
+//   guest     the terminals lane, read-only and redacted; may ask for a hand-off
+export const ROLES = ['owner', 'operator', 'guest']
+
+// One place that says what a role may reach, so no endpoint decides for itself.
+// `cards` is the pipeline side of the board. `machine` is everything that
+// describes this computer rather than the work: the settings, the harness
+// policy, the history index and the worktree map.
+export function mayUseCards(role) { return role === 'owner' || role === 'operator' }
+export function mayUseMachine(role) { return role === 'owner' }
 
 export function sharePath() { return join(home(), 'share.json') }
 
@@ -55,9 +69,49 @@ export function identify(share, presented) {
 export function personNamed(share, name) { return share.people.find((p) => p.name.toLowerCase() === String(name ?? '').toLowerCase()) ?? null }
 export function isOwner(person) { return person?.role === 'owner' }
 
+// ---- TLS ----
+// Leg does not make certificates. It uses a pair you already have, which on a
+// Tailscale network is one command (`tailscale cert <machine>.<tailnet>.ts.net`)
+// and gives a certificate browsers already trust. A self-signed pair would
+// teach everyone on the board to click through a warning, which is worse than
+// no TLS at all on a network that is already private.
+export class TlsRefused extends Error {
+  constructor(msg) { super(msg); this.name = 'TlsRefused'; this.exitCode = 3 }
+}
+
+function tlsPaths(share, env) {
+  return {
+    cert: env.LEG_TLS_CERT || env.BATON_TLS_CERT || share?.tls?.cert || null,
+    key: env.LEG_TLS_KEY || env.BATON_TLS_KEY || share?.tls?.key || null,
+  }
+}
+
+// → { cert, key, cert_path, key_path } | null. Throws TlsRefused when a pair is
+// configured but unusable: a board that quietly fell back to plaintext after
+// being told to use TLS is the one failure this must not have.
+export function readTls(share = readShare(), env = process.env) {
+  const { cert: certPath, key: keyPath } = tlsPaths(share, env)
+  if (!certPath && !keyPath) return null
+  if (!certPath || !keyPath) throw new TlsRefused('TLS needs both a certificate and a key (--tls-cert and --tls-key, or LEG_TLS_CERT and LEG_TLS_KEY)')
+  for (const [label, file] of [['certificate', certPath], ['key', keyPath]]) {
+    if (!existsSync(file)) throw new TlsRefused(`TLS ${label} not found: ${file}`)
+    try { statSync(file) } catch (err) { throw new TlsRefused(`TLS ${label} ${file}: ${err.message}`) }
+  }
+  let cert
+  let key
+  try { cert = readFileSync(certPath) } catch (err) { throw new TlsRefused(`TLS certificate ${certPath}: ${err.message}`) }
+  try { key = readFileSync(keyPath) } catch (err) { throw new TlsRefused(`TLS key ${keyPath}: ${err.message}`) }
+  if (!cert.length || !key.length) throw new TlsRefused('the TLS certificate or key is empty')
+  return { cert, key, cert_path: certPath, key_path: keyPath }
+}
+
+export function tlsConfigured(share = readShare(), env = process.env) { return Boolean(tlsPaths(share, env).cert) }
+
+export function scheme(share = readShare(), env = process.env) { return tlsConfigured(share, env) ? 'https' : 'http' }
+
 export function addPerson(name, { role = 'guest', share = readShare() } = {}) {
   if (!validName(name)) throw new Error(`bad name "${name}": letters, digits, dash and underscore, up to 32 characters`)
-  if (!ROLES.includes(role)) throw new Error(`bad role "${role}" (owner|guest)`)
+  if (!ROLES.includes(role)) throw new Error(`bad role "${role}" (${ROLES.join('|')})`)
   if (personNamed(share, name)) throw new Error(`"${name}" is already on the board; baton share rotate ${name} issues a new link`)
   const token = newToken()
   const person = { name, role, token_sha256: hashToken(token), created_at: new Date().toISOString(), last_seen: null }
@@ -122,7 +176,7 @@ export async function resolveBind(kind = 'tailscale') {
   return lan.address
 }
 
-export function linkFor(share, token) { return `http://${share.bind}:${share.port}/?token=${token}` }
+export function linkFor(share, token) { return `${scheme(share)}://${share.bind}:${share.port}/?token=${token}` }
 
 // Whose terminal this is: BATON_PERSON, else the board's owner, else 'local'.
 export function whoami(share = readShare()) {
@@ -131,9 +185,15 @@ export function whoami(share = readShare()) {
   return share.owner || 'local'
 }
 
-export async function turnOn({ bind = 'tailscale', port = Number(process.env.LEG_PORT || process.env.BATON_PORT || 4747), owner } = {}) {
+export async function turnOn({ bind = 'tailscale', port = Number(process.env.LEG_PORT || process.env.BATON_PORT || 4747), owner, tlsCert = null, tlsKey = null } = {}) {
   const share = readShare()
   const address = await resolveBind(bind)
+  if (tlsCert || tlsKey) {
+    if (!tlsCert || !tlsKey) throw new TlsRefused('TLS needs both --tls-cert and --tls-key')
+    share.tls = { cert: tlsCert, key: tlsKey }
+    // read the pair now, so a bad one fails here and not at the next board start
+    readTls(share, {})
+  }
   share.on = true
   share.bind = address
   share.bind_kind = ['tailscale', 'lan'].includes(String(bind).toLowerCase()) ? String(bind).toLowerCase() : 'address'

package/src/taps/grok.mjs

@@ -183,6 +183,10 @@ const LIMIT_RES = [
   ['grok-rate-limit-event', /"rate_limit"/i],
   ['grok-free-usage-exhausted', /subscription:free-usage-exhausted|You've used all of your free queries/i],
   ['grok-too-many-requests', /TOO_MANY_REQUESTS/],
+  // Observed live 2026-09-17 on grok 1.0.34: an account with no balance left
+  // answers 402, never 429, and none of the strings above appear. Without this
+  // the terminal sat on an exhausted login instead of handing off.
+  ['grok-balance-exhausted', /usage balance exhausted|status 402 Payment Required/i],
 ]
 
 // Scans log or stream text for Grok rate limit signals.

package/src/usage.mjs

@@ -157,21 +157,37 @@ export function candidates({ agent, account = 'default', accounts, order = AGENT
   return out
 }
 
-// → { next: {agent, account} | null, out: [{agent, account, resets_at}] sorted by reset }
+// → { next: {agent, account} | null, out: [{agent, account, resets_at}] sorted
+//     by reset, preferred_taken: bool }
 // `exclude` names (agent, account) pairs this choice must skip: a destination
 // the strict harness policy refused is neither available nor out, it is off
 // the list for this hand-off.
-export function chooseNext({ agent, account, accounts, installed, order = AGENTS, nowS = Math.floor(Date.now() / 1000), exclude = [] }) {
+// `prefer` is a human's pick from the board ("Hand off now to codex"). It wins
+// over the saved order when it is installed, available and not excluded. When
+// it is none of those the order decides instead and `preferred_taken` is false,
+// which is what the session event says: a pick made a minute ago must not leave
+// a terminal stopped because that account walled in the meantime.
+export function chooseNext({ agent, account, accounts, installed, order = AGENTS, nowS = Math.floor(Date.now() / 1000), exclude = [], prefer = null }) {
   const out = []
-  for (const c of candidates({ agent, account, accounts, order })) {
+  const list = candidates({ agent, account, accounts, order })
+  const eligible = (c) => {
+    if (installed && installed[c.agent] === false) return false
+    if (exclude.some((x) => x.agent === c.agent && x.account === c.account)) return false
+    return isAvailable(readUsage(c.agent, c.account), nowS)
+  }
+  if (prefer) {
+    const hit = list.find((c) => c.agent === prefer.agent && c.account === (prefer.account ?? 'default'))
+    if (hit && eligible(hit)) return { next: hit, out, preferred_taken: true }
+  }
+  for (const c of list) {
     if (installed && installed[c.agent] === false) continue
     if (exclude.some((x) => x.agent === c.agent && x.account === c.account)) continue
     const u = readUsage(c.agent, c.account)
-    if (isAvailable(u, nowS)) return { next: c, out }
+    if (isAvailable(u, nowS)) return { next: c, out, preferred_taken: false }
     out.push({ ...c, resets_at: u.limited_until, reason: u.limited_reason })
   }
   out.sort((a, b) => (a.resets_at ?? Infinity) - (b.resets_at ?? Infinity))
-  return { next: null, out }
+  return { next: null, out, preferred_taken: false }
 }
 
 export function fmtReset(epochS) {