@a-company/gnomon 0.0.0-stage → 8.0.2

package/gnomon-mods/ledger/fixtures/over-budget.json

@@ -0,0 +1,86 @@
+{
+  "view": "ledger.strip",
+  "input": {
+    "fixtureEvents": [
+      {
+        "kind": "session.open",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "backend": "claude",
+          "project": 2
+        }
+      },
+      {
+        "kind": "turn.usage",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokens": 40000
+        }
+      },
+      {
+        "kind": "turn.result",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokens": 0,
+          "tokensIn": 12000,
+          "tokensOut": 4000,
+          "cacheRead": 90000,
+          "cacheWrite": 8000,
+          "costMicros": 210000
+        }
+      },
+      {
+        "kind": "session.compacted",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokensBefore": 180000,
+          "tokensAfter": 52000
+        }
+      },
+      {
+        "kind": "turn.result",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokens": 0,
+          "tokensIn": 15000,
+          "tokensOut": 5000,
+          "cacheRead": 39000,
+          "cacheWrite": 18000,
+          "costMicros": 210000
+        }
+      },
+      {
+        "kind": "session.compacted",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokensBefore": 190000,
+          "tokensAfter": 41000
+        }
+      },
+      {
+        "kind": "budget.ladder",
+        "payload": {
+          "dimension": "tokens",
+          "scope": "session",
+          "rung": 90
+        }
+      },
+      {
+        "kind": "budget.usage",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "dimension": "tokens",
+          "n": 182000,
+          "of": 150000,
+          "over": true
+        }
+      }
+    ],
+    "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA"
+  },
+  "width": 80,
+  "prefs": {
+    "motion": "full",
+    "theme": "day"
+  }
+}

package/gnomon-mods/ledger/fixtures/strip-reduced.golden.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": "display-block:v1",
+  "type": "Box",
+  "title": "Ledger · this session",
+  "direction": "row",
+  "children": [
+    {
+      "type": "Text",
+      "text": "●",
+      "tone": "hue-2"
+    },
+    {
+      "type": "Text",
+      "text": "182k in · 9k out · 71% cache · $0.42 · ⇣ 2 compactions (190k → 41k)",
+      "tone": "warn"
+    },
+    {
+      "type": "Text",
+      "text": "▮ tokens 75 of 100% (session daily cap)",
+      "tone": "warn"
+    }
+  ]
+}

package/gnomon-mods/ledger/fixtures/strip-reduced.json

@@ -0,0 +1,76 @@
+{
+  "view": "ledger.strip",
+  "input": {
+    "fixtureEvents": [
+      {
+        "kind": "session.open",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "backend": "claude",
+          "project": 2
+        }
+      },
+      {
+        "kind": "turn.usage",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokens": 40000
+        }
+      },
+      {
+        "kind": "turn.result",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokens": 0,
+          "tokensIn": 12000,
+          "tokensOut": 4000,
+          "cacheRead": 90000,
+          "cacheWrite": 8000,
+          "costMicros": 210000
+        }
+      },
+      {
+        "kind": "session.compacted",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokensBefore": 180000,
+          "tokensAfter": 52000
+        }
+      },
+      {
+        "kind": "turn.result",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokens": 0,
+          "tokensIn": 15000,
+          "tokensOut": 5000,
+          "cacheRead": 39000,
+          "cacheWrite": 18000,
+          "costMicros": 210000
+        }
+      },
+      {
+        "kind": "session.compacted",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokensBefore": 190000,
+          "tokensAfter": 41000
+        }
+      },
+      {
+        "kind": "budget.ladder",
+        "payload": {
+          "dimension": "tokens",
+          "scope": "session",
+          "rung": 75
+        }
+      }
+    ],
+    "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA"
+  },
+  "width": 80,
+  "prefs": {
+    "motion": "reduced",
+    "theme": "day"
+  }
+}

package/gnomon-mods/ledger/fixtures/strip.golden.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "display-block:v1",
+  "type": "Box",
+  "title": "Ledger · this session",
+  "direction": "row",
+  "children": [
+    {
+      "type": "Text",
+      "text": "●",
+      "tone": "hue-2"
+    },
+    {
+      "type": "Text",
+      "text": "182k in · 9k out · 71% cache · $0.42 · ⇣ 2 compactions (190k → 41k)",
+      "tone": "quiet"
+    }
+  ]
+}

package/gnomon-mods/ledger/fixtures/strip.json

@@ -0,0 +1,68 @@
+{
+  "view": "ledger.strip",
+  "input": {
+    "fixtureEvents": [
+      {
+        "kind": "session.open",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "backend": "claude",
+          "project": 2
+        }
+      },
+      {
+        "kind": "turn.usage",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokens": 40000
+        }
+      },
+      {
+        "kind": "turn.result",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokens": 0,
+          "tokensIn": 12000,
+          "tokensOut": 4000,
+          "cacheRead": 90000,
+          "cacheWrite": 8000,
+          "costMicros": 210000
+        }
+      },
+      {
+        "kind": "session.compacted",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokensBefore": 180000,
+          "tokensAfter": 52000
+        }
+      },
+      {
+        "kind": "turn.result",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokens": 0,
+          "tokensIn": 15000,
+          "tokensOut": 5000,
+          "cacheRead": 39000,
+          "cacheWrite": 18000,
+          "costMicros": 210000
+        }
+      },
+      {
+        "kind": "session.compacted",
+        "payload": {
+          "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA",
+          "tokensBefore": 190000,
+          "tokensAfter": 41000
+        }
+      }
+    ],
+    "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA"
+  },
+  "width": 80,
+  "prefs": {
+    "motion": "full",
+    "theme": "day"
+  }
+}

package/gnomon-mods/ledger/gnomon-manifest.json

@@ -0,0 +1,16 @@
+{
+  "manifest": 2,
+  "kind": "mod",
+  "publisher": "gnomon",
+  "name": "ledger",
+  "version": "1.1.0",
+  "abi": "mod-abi:v1",
+  "description": "The Ledger: a context and budget meter (tokens in and out, cache share, cost, compactions, budget rungs and breakers), every number from the kernel's numbers-only feed.",
+  "provides": {
+    "views": [
+      { "id": "ledger.strip", "slot": "composer.footer", "placement": "append", "fixtures": ["fixtures/strip.json", "fixtures/strip-reduced.json", "fixtures/over-budget.json", "fixtures/breaker.json"] },
+      { "id": "ledger.sheet", "slot": "sidebar", "placement": "append", "fixtures": ["fixtures/compacted.json"] }
+    ]
+  },
+  "requires": { "capabilities": ["log.read", "log.read:usage"], "egress": "none" }
+}

package/gnomon-mods/ledger/index.mjs

@@ -0,0 +1,77 @@
+// #ledger-mod (the context and budget meter; first-party, mod-abi:v1, no
+// effects beyond `read`). The #workshop-mod stdio loop, verbatim but for its
+// two views. Runs under #mod-host from its pinned snapshot. Self-contained on
+// purpose: it imports nothing outside this folder, so its packageHash (pinned
+// in the kernel's first-party allowlist) never depends on a build of the SDK.
+// State comes ONLY from the host's projected kernel-event feed (`event`
+// notifications, granted by `log.read`); a fixture render (host-initiated, no
+// relayedFor) may replay `input.fixtureEvents` — a relayed render never can.
+import { apply, emptyState, VIEWS } from './model.mjs';
+
+const ABI = 'mod-abi:v1';
+// Echoed at init; the host refuses any other id (a mod-ABI change needs a new Ledger build).
+const MOD_ABI_ID = 'sha256:7aaf92f46dc35fc35141557c1f89088958f220e6bf53ea31a630bb06430ba082';
+const MAX_FIXTURE_EVENTS = 1024;
+
+const live = emptyState();
+const send = (msg) => process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', ...msg })}\n`);
+
+function handle(method, p) {
+  switch (method) {
+    case 'init':
+      if (p.abi !== ABI) throw Object.assign(new Error(`unsupported abi ${String(p.abi)}`), { code: -32602 });
+      return { abi: ABI, features: [], modAbiId: MOD_ABI_ID };
+    case 'health':
+      return { ok: true, abi: ABI };
+    case 'shutdown':
+      setImmediate(() => process.exit(0));
+      return {};
+    case 'view.render': {
+      const render = Object.hasOwn(VIEWS, p.viewId) ? VIEWS[p.viewId] : null;
+      if (!render) throw Object.assign(new Error(`no view ${String(p.viewId)}`), { code: -32601 });
+      const prefs = p.prefs && typeof p.prefs === 'object' ? p.prefs : {};
+      const fx = !p.relayedFor && p.input && Array.isArray(p.input.fixtureEvents) ? p.input.fixtureEvents.slice(0, MAX_FIXTURE_EVENTS) : null;
+      let state = live;
+      if (fx) {
+        state = emptyState();
+        for (const e of fx) apply(state, e);
+      }
+      // a relayed input may name the focused session (display only); it never carries events
+      const input = p.input && typeof p.input === 'object' && typeof p.input.hsid === 'string' ? { hsid: p.input.hsid } : {};
+      return { block: render(state, prefs, input) };
+    }
+    default:
+      throw Object.assign(new Error(`unknown method ${method}`), { code: -32601 });
+  }
+}
+
+let buf = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf('\n')) >= 0) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (typeof msg.method !== 'string') continue; // the Ledger makes no mod → host requests
+    const params = msg.params && typeof msg.params === 'object' ? msg.params : {};
+    if (msg.method === 'event') {
+      apply(live, params.event);
+      continue;
+    }
+    if (msg.method === 'cancel' || msg.id === undefined) continue;
+    try {
+      send({ id: msg.id, result: handle(msg.method, params) });
+    } catch (e) {
+      send({ id: msg.id, error: { code: typeof e.code === 'number' ? e.code : -32000, message: String(e.message) } });
+    }
+  }
+});
+process.stdin.on('end', () => process.exit(0));

package/gnomon-mods/ledger/model.mjs

@@ -0,0 +1,237 @@
+// #ledger-mod model: the context and budget meter. A pure reducer over the
+// host's NUMBERS-ONLY kernel-event feed (#mod-host projection v2) and a pure
+// render to display-block:v1 (kit:v1 blocks only: Box, Text, Table, Progress).
+// Inputs: turn.usage/turn.result {hsid, tokens, tokensIn?, tokensOut?,
+// cacheRead?, cacheWrite?, costMicros?}, session.compacted {hsid,
+// tokensBefore, tokensAfter}, session.open {hsid, backend, project},
+// session.exited, budget.usage {dimension, n, of?, over?}, budget.ladder
+// {dimension, scope, rung}, budget.breaker.open/close {dimension},
+// permit.deny {dimension}. Unknown kinds and malformed fields are ignored;
+// every number is re-clamped here (a mod never trusts a count).
+
+export const MAX_SESSIONS = 256;
+export const MAX_DIMENSIONS = 32;
+export const HUES = 8;
+export const WARN_RUNG = 75;
+const ID = /^[A-Za-z0-9:._-]{1,128}$/;
+const TOKEN = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** A finite non-negative safe integer (anything else is 0). */
+export function count(v) {
+  if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) return 0;
+  return Math.min(Math.floor(v), Number.MAX_SAFE_INTEGER);
+}
+const token = (v, d = 'unknown') => (typeof v === 'string' && TOKEN.test(v) ? v : d);
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+
+export function emptyState() {
+  return { sessions: new Map(), permit: null, ladder: new Map(), breakers: new Set(), denies: new Map() };
+}
+
+function session(state, hsid) {
+  let s = state.sessions.get(hsid);
+  if (s) return s;
+  if (state.sessions.size >= MAX_SESSIONS) state.sessions.delete(state.sessions.keys().next().value);
+  s = { backend: 'claude', project: 0, open: true, tokens: 0, tokensIn: 0, tokensOut: 0, cacheRead: 0, cacheWrite: 0, split: false, costMicros: 0, cost: false, compactions: 0, lastBefore: 0, lastAfter: 0 };
+  state.sessions.set(hsid, s);
+  return s;
+}
+
+const boundedSet = (m, k, v) => {
+  if (!m.has(k) && m.size >= MAX_DIMENSIONS) return;
+  m.set(k, v);
+};
+
+/** Apply one projected kernel event. */
+export function apply(state, event) {
+  if (!event || typeof event !== 'object' || typeof event.kind !== 'string') return state;
+  const p = event.payload && typeof event.payload === 'object' ? event.payload : {};
+  const hsid = typeof p.hsid === 'string' && ID.test(p.hsid) ? p.hsid : null;
+  switch (event.kind) {
+    case 'session.open': {
+      if (!hsid) break;
+      const s = session(state, hsid);
+      s.backend = p.backend === 'local' ? 'local' : 'claude';
+      s.project = Number.isInteger(p.project) && p.project >= 0 && p.project < HUES ? p.project : 0;
+      s.open = true;
+      break;
+    }
+    case 'session.exited': {
+      const s = hsid && state.sessions.get(hsid);
+      if (s) s.open = false;
+      break;
+    }
+    case 'turn.usage':
+    case 'turn.result': {
+      if (!hsid) break;
+      const s = session(state, hsid);
+      s.tokens += count(p.tokens);
+      if (event.kind === 'turn.result') {
+        for (const k of ['tokensIn', 'tokensOut', 'cacheRead', 'cacheWrite']) {
+          if (isNum(p[k])) {
+            s[k] += count(p[k]);
+            s.split = true;
+          }
+        }
+        if (isNum(p.costMicros)) {
+          s.costMicros += count(p.costMicros);
+          s.cost = true;
+        }
+      }
+      break;
+    }
+    case 'session.compacted': {
+      if (!hsid) break;
+      const s = session(state, hsid);
+      s.compactions++;
+      s.lastBefore = count(p.tokensBefore);
+      s.lastAfter = count(p.tokensAfter);
+      break;
+    }
+    case 'budget.usage':
+      if (p.over === true) state.permit = { dimension: token(p.dimension, 'tokens'), n: count(p.n), of: count(p.of) };
+      break;
+    case 'budget.ladder': {
+      const key = `${token(p.dimension)}|${token(p.scope, 'session')}`;
+      const rung = Math.min(count(p.rung), 1000);
+      if (rung > (state.ladder.get(key) ?? -1)) boundedSet(state.ladder, key, rung);
+      break;
+    }
+    case 'budget.breaker.open':
+      if (state.breakers.size < MAX_DIMENSIONS) state.breakers.add(token(p.dimension));
+      break;
+    case 'budget.breaker.close':
+      state.breakers.delete(token(p.dimension));
+      break;
+    case 'permit.deny': {
+      const d = token(p.dimension);
+      boundedSet(state.denies, d, (state.denies.get(d) ?? 0) + 1);
+      break;
+    }
+    default:
+      break;
+  }
+  return state;
+}
+
+/** 182000 → 182k, 9400 → 9k, 1250000 → 1.3M, 950 → 950. */
+export function short(n) {
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${Math.round(n / 1000)}k`;
+  return `${(Math.round(n / 100_000) / 10).toFixed(1)}M`;
+}
+const dollars = (micros) => `$${(micros / 1e6).toFixed(2)}`;
+
+/** The totals of one session, or of every session when hsid is null. */
+export function totals(state, hsid) {
+  const list = hsid ? [state.sessions.get(hsid)].filter(Boolean) : [...state.sessions.values()];
+  const t = { tokens: 0, tokensIn: 0, tokensOut: 0, cacheRead: 0, cacheWrite: 0, split: false, unsplit: 0, costMicros: 0, cost: false, compactions: 0, lastBefore: 0, lastAfter: 0 };
+  for (const s of list) {
+    for (const k of ['tokens', 'tokensIn', 'tokensOut', 'cacheRead', 'cacheWrite', 'costMicros', 'compactions']) t[k] = Math.min(t[k] + s[k], Number.MAX_SAFE_INTEGER);
+    t.split ||= s.split;
+    if (!s.split) t.unsplit = Math.min(t.unsplit + s.tokens, Number.MAX_SAFE_INTEGER);
+    t.cost ||= s.cost;
+    if (s.compactions) {
+      t.lastBefore = s.lastBefore;
+      t.lastAfter = s.lastAfter;
+    }
+  }
+  return t;
+}
+
+/** `182k in · 9k out · 71% cache · $0.42 · ⇣ 2 compactions (190k → 41k)`; `in` counts every input token (fresh + cache). */
+export function summaryLine(t) {
+  const parts = [];
+  if (t.split) {
+    const input = t.tokensIn + t.cacheRead + t.cacheWrite;
+    parts.push(`${short(input)} in`, `${short(t.tokensOut)} out`, `${input ? Math.round((t.cacheRead / input) * 100) : 0}% cache`);
+    if (t.unsplit) parts.push(`${short(t.unsplit)} local`);
+  } else parts.push(`${short(t.tokens)} tokens`);
+  if (t.cost) parts.push(dollars(t.costMicros));
+  if (t.compactions) parts.push(`⇣ ${t.compactions} compaction${t.compactions === 1 ? '' : 's'} (${short(t.lastBefore)} → ${short(t.lastAfter)})`);
+  return parts.join(' · ');
+}
+
+/** The worst budget signal: deny (vermilion) > warn (amber) > none. */
+export function budgetTone(state) {
+  if (state.breakers.size || state.denies.size) return 'deny';
+  if (state.permit) return 'warn';
+  for (const r of state.ladder.values()) if (r >= WARN_RUNG) return 'warn';
+  return 'quiet';
+}
+
+/** The budget meter: the over-permit row (n of m), else the highest ladder rung (percent of the daily cap). */
+function meter(state, reduced) {
+  let m = null;
+  if (state.permit && state.permit.of > 0) {
+    const fmt = state.permit.dimension === 'usd' ? dollars : short;
+    m = { value: state.permit.n, max: state.permit.of, label: `${state.permit.dimension} ${fmt(state.permit.n)} of ${fmt(state.permit.of)} (permit)` };
+  } else {
+    let best = null;
+    for (const [k, r] of [...state.ladder.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) if (!best || r > best[1]) best = [k, r];
+    if (best) {
+      const [dim, scope] = best[0].split('|');
+      m = { value: best[1], max: 100, label: `${dim} ${best[1]} of 100% (${scope} daily cap)` };
+    }
+  }
+  if (!m) return [];
+  // reduced motion: no fill element at all (nothing can animate), the same numbers as text
+  return reduced ? [{ type: 'Text', text: `▮ ${m.label}`, tone: budgetTone(state) }] : [{ type: 'Progress', value: Math.min(m.value, m.max), max: m.max, label: m.label }];
+}
+
+function alarms(state) {
+  const out = [];
+  for (const d of [...state.breakers].sort()) out.push({ type: 'Text', text: `✕ breaker open · ${d}`, tone: 'deny' });
+  for (const [d, n] of [...state.denies.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) out.push({ type: 'Text', text: `✕ permit denied · ${d}${n > 1 ? ` ×${n}` : ''}`, tone: 'deny' });
+  return out;
+}
+
+/** The strip (composer.footer): the cap carries the session's project hue (never as text). */
+export function renderStrip(state, prefs = {}, input = {}) {
+  const reduced = prefs.motion === 'reduced';
+  const hsid = input && typeof input.hsid === 'string' && ID.test(input.hsid) && state.sessions.has(input.hsid) ? input.hsid : null;
+  const s = hsid ? state.sessions.get(hsid) : null;
+  const t = totals(state, hsid);
+  const tone = budgetTone(state);
+  const cap = s ? { type: 'Text', text: s.backend === 'local' ? '○' : '●', tone: `hue-${s.project}` } : { type: 'Text', text: '◌', tone: 'quiet' };
+  return {
+    schemaVersion: 'display-block:v1',
+    type: 'Box',
+    title: hsid ? 'Ledger · this session' : `Ledger · ${state.sessions.size} session${state.sessions.size === 1 ? '' : 's'}`,
+    direction: 'row',
+    children: [cap, { type: 'Text', text: state.sessions.size ? summaryLine(t) : 'no usage yet', tone: tone === 'deny' ? 'deny' : tone === 'warn' ? 'warn' : 'quiet' }, ...meter(state, reduced), ...alarms(state)],
+  };
+}
+
+/** The sheet (sidebar): one row per session, then the budget meter and alarms. */
+export function renderSheet(state, prefs = {}) {
+  const reduced = prefs.motion === 'reduced';
+  const rows = [...state.sessions.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+    .map(([id, s]) => {
+      const input = s.tokensIn + s.cacheRead + s.cacheWrite;
+      return [
+        `…${id.slice(-6)}${s.open ? '' : ' (ended)'}`,
+        s.split ? short(input) : short(s.tokens),
+        s.split ? short(s.tokensOut) : '-',
+        s.split ? `${input ? Math.round((s.cacheRead / input) * 100) : 0}%` : '-',
+        s.cost ? dollars(s.costMicros) : '-',
+        s.compactions ? `${s.compactions} (${short(s.lastBefore)} → ${short(s.lastAfter)})` : '0',
+      ];
+    });
+  const t = totals(state, null);
+  return {
+    schemaVersion: 'display-block:v1',
+    type: 'Box',
+    title: 'Ledger',
+    direction: 'column',
+    children: [
+      rows.length ? { type: 'Table', columns: ['session', 'in', 'out', 'cache', 'cost', '⇣ compactions'], rows } : { type: 'Text', text: 'no sessions metered yet', tone: 'quiet' },
+      ...(rows.length ? [{ type: 'Text', text: `total · ${summaryLine(t)}`, tone: 'quiet' }] : []),
+      ...meter(state, reduced),
+      ...alarms(state),
+    ],
+  };
+}
+
+export const VIEWS = Object.freeze({ 'ledger.strip': renderStrip, 'ledger.sheet': renderSheet });

package/gnomon-mods/neurons/README.md

@@ -0,0 +1,31 @@
+# gnomon.neurons (first-party Gnomon mod)
+
+Neurons puts the user's personal knowledge brain on the Desk. It has no view and no process of its own: it declares the Neurons MCP server, three offers and a playbook skill.
+
+- **search-the-brain** (diverge, `neuron_search`): check what is already known before researching a topic from scratch.
+- **capture-a-learning** (synthesize, `source_note`): save something verified first-hand in this session as a citable source note.
+- **capture-a-decision** (commit, `neuron_write`): write a decision with its reasons as neurons that cite a source.
+
+The mod id is `gnomon.neurons` (manifest: 2, publisher `gnomon`, slice S0b), which is what the model writes in an offer block. Before S0b it was `neurons-brain`, because the bare name `neurons` is a kernel namespace token (the §9.1 `neurons.event` kind); under a publisher its events live in `modns.gnomon.neurons.*`, so the first-party name is allowed for publisher `gnomon` only. The kernel names its MCP server `gm_gnomon_neurons` (manifest: 2 entries carry no name). `NEURONS_VAULT` is the upstream server's own variable, so it keeps its name (first-party env names are exempt from the `<PUB>__<NAME>__` own-prefix).
+
+Each offer's restraint text says when not to offer it. `skills/neurons-desk/SKILL.md` is the playbook. Outside Gnomon it falls back to plain one-sentence suggestions.
+
+It requires no capability and lists no egress. The MCP server reads and writes the vault on the user's own machine.
+
+## Install
+
+```
+gnomon mod install packages/gnomon-mods/neurons
+```
+
+Approve the card in the GUI. The manifest's default launch, `neurons mcp`, is generic and is not an absolute path, so the server fails closed (it is never launched) until you set a per-user override. The manifest declares `config: {command, args, env: [NEURONS_VAULT]}`. Set the override with `gnomon mod config` (slice S1):
+
+- the command: the absolute path of your node (`which node`)
+- the args: `<your a-neurons checkout>/dist/cli/main.js mcp`
+- `NEURONS_VAULT`: your vault folder
+
+An override command must be an absolute path; a bare `node` is refused. The override belongs to you and is never committed.
+
+Before the model saves anything with `source_note` or `neuron_write`, the playbook has it show you the exact text and wait for you to confirm or edit it. It also flags any part that came from fetched pages, tool output or unverified files.
+
+The packageHash is pinned in the kernel's first-party list, so editing any file here needs a new pin: run `npm run repin:first-party` in packages/gnomon (it also regenerates the offer goldens in `fixtures/`).

package/gnomon-mods/neurons/fixtures/capture-a-decision.golden.json

@@ -0,0 +1,20 @@
+{
+  "offer": {
+    "mod": "gnomon.neurons",
+    "kind": "capture-a-decision",
+    "question": "Want me to save this decision and its reasons to the brain?"
+  },
+  "body": "So we go with SQLite over Postgres for the local store: one file, no daemon, and the write volume fits.",
+  "shown": {
+    "mod": "gnomon.neurons",
+    "kind": "capture-a-decision",
+    "phase": "commit",
+    "title": "Save this decision to the brain",
+    "contextIn": [
+      "recent-messages",
+      "session-summary"
+    ],
+    "question": "Want me to save this decision and its reasons to the brain?",
+    "handoffTool": "neuron_write"
+  }
+}

package/gnomon-mods/neurons/fixtures/capture-a-decision.json

@@ -0,0 +1,3 @@
+{
+  "reply": "So we go with SQLite over Postgres for the local store: one file, no daemon, and the write volume fits.\n\n```offer\n{\"mod\":\"gnomon.neurons\",\"kind\":\"capture-a-decision\",\"question\":\"Want me to save this decision and its reasons to the brain?\"}\n```\n"
+}