karajan-code 4.21.0 → 4.23.0

package/README.md

@@ -9,8 +9,8 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/v/karajan-code.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/dw/karajan-code.svg" alt="npm downloads"></a>
+  <a href="https://www.npmjs.com/package/@karajan-family/code"><img src="https://img.shields.io/npm/v/%40karajan-family%2Fcode.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@karajan-family/code"><img src="https://img.shields.io/npm/dw/%40karajan-family%2Fcode.svg" alt="npm downloads"></a>
   <a href="https://github.com/manufosela/karajan-code/actions"><img src="https://github.com/manufosela/karajan-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node.js"></a>
@@ -34,6 +34,7 @@ Your AI agent (Claude Code, Codex, Copilot, Antigravity, Cursor…) writes the c
 - **Nothing personal ships** — every outbound boundary audits before it leaves the machine: the pre-commit rejects a staged diff carrying your denylisted personal data, hardcoded platform tokens (`ghp_`, `sk-`, `AKIA`…) block outright, `verify-pack`-style tarball scans guard the publish, and `kj privacy scan <dir>` audits any build output. Your denylist lives in `~/.karajan/privacy.yml` — the install asks and writes it for you.
 - **Installing IS activating** — `kj env install` performs the enforcement itself (git hooks, verdict gate, tool gate) instead of trusting the agent to run setup steps, and ends by printing the method into the very conversation that installed it. A commit outside the method is rejected, not narrated.
 - **The turn cannot end red — the Sentinel** — a deterministic supervisor (zero LLM) wired into the harness's synchronous hooks records the method state of the session as tools run, and a Stop hook blocks the agent from ending its turn while method violations are open. The program rules, the agent thinks. See [guarantee levels](#guarantee-levels-governed-vs-supervised).
+- **Trust expires — the Steward** — `kj steward sweep` checks the project's declared guarantees against their freshness and answers one of FOUR verdicts per invariant: ok, broken, *unknown* (evidence expired → refresh it) or *not observable* (nowhere to look → instrument it) — because confusing the last two with green is how a project decays for weeks behind a passing facade. The verdict is versioned in the repo, sealed in the decision chain, and every break lands on the board as PROPOSED work that nothing executes unreviewed. Runs on demand, on `kj resume` when stale, or as an opt-in scheduled Action.
 - **The review panel never runs dry** — nine built-in agents (Claude Code, Codex, GitHub Copilot, Antigravity `agy` — the gemini successor —, Kimi Code, Qwen, OpenCode, Aider, Gemini legacy), and when the configured reviewer exhausts its quota, `kj review` switches to an authenticated candidate with a LOUD notice — or hands you the menu of candidates with their tier (free / subscription / local) and the exact login command. Never a silent failure, never the brain reviewing itself.
 
 This repo runs under its own environment: every commit to karajan-code carries a cross-AI verdict.
@@ -58,7 +59,7 @@ kj init && kj env install && kj harden && kj review --install-gate
 git config core.hooksPath .karajan/hooks
 ```
 
-Requires git and at least one AI agent CLI — two enables cross-AI review; three enables arbitration. All install routes (npm, binaries, brew, Python wrapper) in the [install docs](https://karajancode.com/docs/v4/install/).
+Requires git and at least one AI agent CLI — two enables cross-AI review; three enables arbitration. The npm route is `npm install -g @karajan-family/code` (published as `karajan-code` before joining the scope; the legacy name still installs the same versions). All install routes (npm, binaries, brew, Python wrapper) in the [install docs](https://karajancode.com/docs/v4/install/).
 
 ## The daily loop
 
@@ -85,6 +86,8 @@ With a declared `.karajan/policy.yml`, the policy layer enforces at three tiers,
 
 Tier B is the guarantee floor — hosts without hooks lose A, never B; C re-verifies both. Security-class rules and consumer defaults are non-exemptable at every tier: no escape, no arbitration, no grant.
 
+Every chokepoint decision lands in a hash-chained log (`kj policy anchor` seals its head in git), and `kj policy report` turns that log into evidence of process: per rule, how often it warned, denied or was exempted, which denials are still open, which grants are alive, expired or renewed — so a rule "gains teeth" on data, not on a hunch, and a renewed exception is read for what it is: the policy asking to change.
+
 ## Headless mode
 
 The classic multiagent pipeline lives on for CI and automation: `kj run "<task>"` orchestrates coder/reviewer/tester subprocess roles unattended, with the same gates. Agents and CI pass `--non-interactive` (or `KJ_NON_INTERACTIVE=1`): safe gates auto-answer, FAIL findings stop the run with a real exit code. `kj advanced` lists the full surface. [Headless mode docs](https://karajancode.com/docs/v4/headless/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.21.0",
+  "version": "4.23.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -38,7 +38,8 @@
     "packages/ai-trash",
     "packages/core",
     "packages/hu-board",
-    "packages/governance"
+    "packages/governance",
+    "packages/console"
   ],
   "imports": {
     "#utils/*": "./src/utils/*",
@@ -126,12 +127,14 @@
     "esbuild": "^0.28.0",
     "eslint": "^10.4.1",
     "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-node-security": "5.2.2",
     "eslint-plugin-security": "^4.0.0",
     "globals": "^17.6.0",
     "lint-staged": "^17.0.7",
     "postject": "^1.0.0-alpha.6",
     "prettier": "^3.4.2",
     "simple-git-hooks": "^2.13.1",
+    "smol-toml": "^1.7.0",
     "vitest": "^4.1.8"
   }
 }

package/packages/hu-board/public/app.js

@@ -192,6 +192,7 @@ function render() {
     case 'board': return renderBoard();
     case 'sessions': return renderSessions();
     case 'graph': return renderGraph();
+    case 'governance': return renderGovernance();
     default: return renderDashboard();
   }
 }

package/packages/hu-board/public/index.html

@@ -24,6 +24,7 @@
       <button class="nav-btn" data-view="graph" title="Dependency graph of the selected project's HUs — who blocks whom. Useful before scheduling work.">Graph</button>
       <button class="nav-btn" data-view="dashboard" title="Per-project landing: stats grid + project list. Click a project card to focus the kanban / graph on that project.">Dashboard</button>
       <button class="nav-btn" data-view="sessions" title="Every kj run that has touched the board, newest first. Filter by project; click a session to inspect its iterations, commits and checkpoints.">Sessions</button>
+      <button class="nav-btn" data-view="governance" title="The acta: policy rules by friction, the hash-chained decision log and its anchor, standing exceptions with owner and expiry, renewals and signals.">Governance</button>
       <a class="nav-btn" href="/pipeline.html" title="Live observability of pipeline runs (Karajan v2.7+): stage timings, agent calls, decision logs.">Pipeline</a>
       <a class="nav-btn" href="/rag.html" title="RAG retrieval-quality dashboard: chunk counts, embedder provider, db size.">RAG</a>
       <a class="nav-btn" href="/wiki.html" title="Search the per-project QMD semantic wiki (docs, plans, reviews).">Wiki</a>
@@ -59,6 +60,7 @@
   <script src="/utils/board-view.js"></script>
   <script src="/utils/dashboard-view.js"></script>
   <script src="/utils/graph-view.js"></script>
+  <script src="/utils/governance-view.js"></script>
   <script src="/utils/project-picker-view.js"></script>
   <script src="/utils/story-detail-view.js"></script>
   <script src="/utils/preflight-view.js"></script>

package/packages/hu-board/public/styles.css

@@ -826,6 +826,28 @@ a:hover {
 }
 
 /* ---- Empty State ---- */
+/* GUI-B (KJC-TSK-0772) — governance view */
+.gov-dir { display: flex; gap: 0.5rem; align-items: center; }
+.gov-dir__input { min-width: 18rem; padding: 0.3rem 0.5rem; font-family: inherit; }
+.gov-btn { padding: 0.3rem 0.75rem; cursor: pointer; }
+.gov-note { margin: 0.5rem 0; opacity: 0.85; }
+.gov-note--warn { color: #d9a400; }
+.gov-red { color: #e5484d; }
+.gov-small { font-size: 1.1rem; line-height: 1.4; }
+.gov-scroll { overflow-x: auto; max-width: 100%; }
+.gov-table { width: 100%; border-collapse: collapse; font-size: 0.9rem; }
+.gov-table th, .gov-table td { padding: 0.4rem 0.6rem; text-align: left; border-bottom: 1px solid rgba(128, 128, 128, 0.25); white-space: nowrap; }
+.gov-badge { display: inline-block; padding: 0.1rem 0.45rem; border-radius: 999px; font-size: 0.75rem; border: 1px solid currentColor; }
+.gov-badge--deny { color: #e5484d; }
+.gov-badge--warn { color: #d9a400; }
+.gov-badge--security { color: #b44dff; }
+.gov-row--soon td { background: rgba(217, 164, 0, 0.12); }
+.gov-list { margin: 0.5rem 0 1rem 1.25rem; }
+.gov-grant { display: flex; flex-wrap: wrap; gap: 0.5rem; align-items: center; margin: 0.75rem 0; }
+.gov-grant select, .gov-grant input { padding: 0.3rem 0.5rem; font-family: inherit; }
+.gov-pre { white-space: pre-wrap; font-size: 0.85rem; margin: 0 0 1rem; max-height: 18rem; overflow: auto; }
+.gov-pre:empty { display: none; }
+
 .empty-state {
   text-align: center;
   padding: 60px 20px;

package/packages/hu-board/public/utils/governance-view.js

@@ -0,0 +1,149 @@
+// GUI-B (KJC-TSK-0772) — Governance view: the "acta". A live exception is
+// invisible; here every rule shows its friction, every grant its owner and
+// expiry, every renewal its count. Read-only (actions land in GUI-C).
+// Classic script (no exports), same conventions as dashboard-view.js:
+// api() from utils/api.js, esc() from formatters.js.
+
+const GOV_DIR_KEY = 'kj.governance.dir';
+let govBusy = false;
+
+async function renderGovernance() {
+  const app = document.getElementById('app');
+  // Server-push re-renders the current view on every event; never wipe a
+  // form the user is typing in or a proposal still being translated.
+  const typing = () => { const a = document.activeElement; return govBusy || Boolean(a && a.id && a.id.startsWith('gov-') && app.contains(a)); };
+  if (typing()) return;
+  const dir = localStorage.getItem(GOV_DIR_KEY) || '';
+  app.innerHTML = '<div class="loading"><div class="loading__spinner"></div><p>Loading governance...</p></div>';
+  try {
+    const data = await api('/api/governance' + (dir ? '?dir=' + encodeURIComponent(dir) : ''));
+    if (typing()) return; // the user started typing while we fetched: keep their form
+    if (!data || data.ok === false) {
+      app.innerHTML = govDirForm((data && data.dir) || dir) + `<div class="empty-state"><div class="empty-state__title">Governance unavailable</div><div class="empty-state__text">${esc((data && data.error) || 'governance unavailable')}</div><div class="empty-state__path">Type the absolute directory of a project that ran <code>kj harden</code> and press Load.</div></div>`;
+      return;
+    }
+    localStorage.setItem(GOV_DIR_KEY, data.dir);
+    app.innerHTML = govDirForm(data.dir) + govIdentity(data.identity) + govChain(data.report, data.anchor) + govRules(data.policy, data.report) + govGrants(data.report.grants, data.policy) + govSignals(data.report.signals);
+  } catch (err) {
+    app.innerHTML = govDirForm(dir) + `<div class="empty-state"><div class="empty-state__title">Governance unavailable</div><div class="empty-state__text">${esc(err.message)}</div></div>`;
+  }
+}
+
+function govSetDir() {
+  localStorage.setItem(GOV_DIR_KEY, document.getElementById('gov-dir').value.trim());
+  renderGovernance();
+}
+
+// GUI-C (KJC-TSK-0773): actions call the same CLI commands through the board.
+async function govPost(path, body) {
+  const res = await fetch(path, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ dir: localStorage.getItem(GOV_DIR_KEY) || '', ...body }) });
+  const data = await res.json().catch(() => ({ ok: false, error: `API error: ${res.status}` }));
+  return data;
+}
+
+function govSay(text, warn) {
+  const el = document.getElementById('gov-msg');
+  if (el) { el.textContent = text; el.className = warn ? 'gov-note gov-note--warn' : 'gov-note'; }
+}
+
+// Spoken rule: propose shows the diff kj would write; apply asks first, then --yes.
+async function govRule(apply) {
+  const text = document.getElementById('gov-rule-text').value.trim();
+  const out = document.getElementById('gov-rule-out');
+  if (!text) return govSay('say the rule first', true);
+  if (apply && !(await showConfirm(`Write this rule into .karajan/policy.yml?\n\n${text}\n\nThe diff shown below is what lands.`, { title: 'Apply rule', okLabel: 'Apply' }))) return;
+  govRuleText = text;
+  govRuleOut = apply ? 'applying…' : 'translating…';
+  out.textContent = govRuleOut;
+  govBusy = true;
+  const r = await govPost('/api/governance/rule', { text, apply: apply === true }).finally(() => { govBusy = false; });
+  govRuleOut = r.output || r.error || '';
+  const pre = document.getElementById('gov-rule-out');
+  if (pre) pre.textContent = govRuleOut;
+  if (!r.ok) return govSay(r.error || 'rule refused', true);
+  if (apply) { govRuleText = ''; renderGovernance(); }
+}
+
+async function govAnchor() {
+  const r = await govPost('/api/governance/anchor', {});
+  if (!r.ok) return govSay(r.error || 'anchor failed', true);
+  renderGovernance();
+}
+
+async function govGrant() {
+  const rule = document.getElementById('gov-grant-rule').value.trim();
+  const until = document.getElementById('gov-grant-until').value;
+  const reason = document.getElementById('gov-grant-reason').value.trim();
+  if (!rule || !until || !reason) return govSay('rule, until and reason are required — an exception without who/why/until is a hole', true);
+  const iso = new Date(`${until}T23:59:59Z`).toISOString();
+  if (!(await showConfirm(`Grant a standing exception to ${rule} until ${iso}?\n\n${reason}\n\nIt is recorded with this clone's declared identity and expires on its own.`, { title: 'Grant exception', okLabel: 'Grant' }))) return;
+  const r = await govPost('/api/governance/grant', { rule, until: iso, reason });
+  if (!r.ok) return govSay(r.error || 'grant refused', true);
+  renderGovernance();
+}
+
+const govDirForm = (dir) => `
+  <div class="section-header"><span class="section-header__title">Governance</span>
+    <span class="gov-dir"><input id="gov-dir" class="gov-dir__input" value="${esc(dir)}" placeholder="/absolute/project/dir" aria-label="Project directory">
+    <button class="gov-btn" onclick="govSetDir()">Load</button></span></div>`;
+
+const govIdentity = (id) => id && id.declared
+  ? `<p class="gov-note">Identity declared for this clone: <strong>${esc(id.gh_user)}</strong> · ${esc(id.git_email)}</p>`
+  : '<p class="gov-note gov-note--warn">Identity NOT declared for this clone — <code>kj identity set</code> (the Sentinel fails closed on gh and mutating git until then).</p>';
+
+function govChain(report, anchor) {
+  const d = report.decisions;
+  const chain = report.chain.ok
+    ? `<div class="stat-card__value stat-card__value--green">intact</div><div class="stat-card__label">chain · ${report.chain.length} decisions</div>`
+    : `<div class="stat-card__value gov-red">BROKEN</div><div class="stat-card__label">at entry ${esc(String(report.chain.at))} — ${esc(report.chain.reason || '')}</div>`;
+  const anchorBtn = report.chain.ok && (anchor.stale || !anchor.sealed) ? ' <button class="gov-btn" onclick="govAnchor()">Anchor now</button>' : '';
+  const anch = !anchor.sealed
+    ? `<div class="stat-card__value stat-card__value--yellow">none</div><div class="stat-card__label">anchor${anchorBtn}</div>`
+    : `<div class="stat-card__value ${anchor.stale ? 'stat-card__value--yellow' : 'stat-card__value--green'}">${anchor.length}/${anchor.current}</div><div class="stat-card__label">anchored · ${anchor.stale ? 're-seal pending' : 'up to date'}${anchorBtn}</div>`;
+  const cps = Object.entries(d.chokepoints || {}).map(([k, v]) => `${esc(k)} ${v}`).join(' · ') || 'none';
+  return `<div class="stats-grid">
+    <div class="stat-card">${chain}</div><div class="stat-card">${anch}</div>
+    <div class="stat-card"><div class="stat-card__value">${d.allow}</div><div class="stat-card__label">allow</div></div>
+    <div class="stat-card"><div class="stat-card__value ${d.deny ? 'gov-red' : ''}">${d.deny}</div><div class="stat-card__label">deny · ${d.open} open</div></div>
+    <div class="stat-card"><div class="stat-card__value stat-card__value--purple">${d.exempt}</div><div class="stat-card__label">exempt</div></div>
+    <div class="stat-card"><div class="stat-card__value gov-small">${esc(cps)}</div><div class="stat-card__label">chokepoints</div></div></div>`;
+}
+
+function govRules(policy, report) {
+  const rows = new Map();
+  for (const r of policy.rules || []) rows.set(r.rule_id, { ...r, warns: 0, denies: 0, exempts: 0, open: 0 });
+  for (const i of policy.invariants || []) rows.set(i.id, { rule_id: i.id, enforcement: i.enforcement, class: null, warns: 0, denies: 0, exempts: 0, open: 0 });
+  for (const r of report.rules || []) rows.set(r.rule_id, { ...(rows.get(r.rule_id) || {}), ...r });
+  const head = policy.declared
+    ? (policy.error ? `<p class="gov-note gov-note--warn">policy.yml invalid: ${esc(policy.error)}</p>` : '')
+    : '<p class="gov-note">No <code>.karajan/policy.yml</code> declared — only the consumer defaults apply. Speak a rule: <code>kj policy add "…"</code>.</p>';
+  if (rows.size === 0) return `<div class="section-header"><span class="section-header__title">Rules</span></div>${head}<p class="gov-note">No rule has warned or denied yet.</p>${govRuleBox()}`;
+  const body = [...rows.values()].sort((a, b) => (b.denies + b.warns) - (a.denies + a.warns)).map((r) => `
+    <tr><td><code>${esc(r.rule_id)}</code></td><td><span class="gov-badge gov-badge--${esc(r.enforcement || 'warn')}">${esc(r.enforcement || 'warn')}</span>${r.class === 'security' ? ' <span class="gov-badge gov-badge--security" title="non-exemptable: no escape, no arbitration, no grant">security</span>' : ''}</td>
+    <td>${r.warns}</td><td class="${r.denies ? 'gov-red' : ''}">${r.denies}</td><td>${r.exempts}</td><td class="${r.open ? 'gov-red' : ''}">${r.open}</td></tr>`).join('');
+  return `<div class="section-header"><span class="section-header__title">Rules by friction</span><span class="section-header__count">${rows.size}</span></div>${head}
+    <div class="gov-scroll"><table class="gov-table"><thead><tr><th>rule</th><th>enforcement</th><th>warn</th><th>deny</th><th>exempt</th><th>open</th></tr></thead><tbody>${body}</tbody></table></div>${govRuleBox()}`;
+}
+
+// Typed text and the last proposal survive the server-push re-renders.
+let govRuleText = '';
+let govRuleOut = '';
+const govRuleBox = () => `<div class="gov-grant"><input id="gov-rule-text" class="gov-dir__input" value="${esc(govRuleText)}" oninput="govRuleText=this.value" placeholder="say a rule: the coder never writes .env files" aria-label="Spoken rule">
+  <button class="gov-btn" onclick="govRule(false)">Propose</button><button class="gov-btn" onclick="govRule(true)">Apply</button></div><pre id="gov-rule-out" class="gov-pre" aria-live="polite">${esc(govRuleOut)}</pre>`;
+
+function govGrants(g, policy) {
+  const soon = new Set((g.soon || []).map((e) => e.ts || e.expiresAt + e.rule_id));
+  const row = (e) => `<tr class="${soon.has(e.ts || e.expiresAt + e.rule_id) ? 'gov-row--soon' : ''}"><td><code>${esc(e.rule_id)}</code></td><td>${esc(e.expiresAt || '')}</td><td>${esc((e.who && e.who.git) || '?')}</td><td>${esc(e.justification || '')}</td></tr>`;
+  const alive = (g.alive || []).length
+    ? `<div class="gov-scroll"><table class="gov-table"><thead><tr><th>rule</th><th>until</th><th>granted by</th><th>why</th></tr></thead><tbody>${g.alive.map(row).join('')}</tbody></table></div>`
+    : '<p class="gov-note">No standing exception alive.</p>';
+  const renewals = (g.renewals || []).map((r) => `<li class="gov-red"><code>${esc(r.rule_id)}</code> granted ${r.count} times — a renewed exception is the policy asking to change</li>`).join('');
+  // Only non-security rules can be granted: the inexemptable never gets a form.
+  const grantable = (policy.rules || []).filter((r) => r.class !== 'security').map((r) => `<option value="${esc(r.rule_id)}">${esc(r.rule_id)}</option>`).join('');
+  const form = grantable
+    ? `<div class="gov-grant"><select id="gov-grant-rule" aria-label="Rule">${grantable}</select><input id="gov-grant-until" type="date" aria-label="Until"><input id="gov-grant-reason" class="gov-dir__input" placeholder="why, written now" aria-label="Reason"><button class="gov-btn" onclick="govGrant()">Grant until</button></div>`
+    : '<p class="gov-note">Nothing grantable: no declared non-security rule.</p>';
+  return `<div class="section-header"><span class="section-header__title">Standing exceptions</span><span class="section-header__count">${(g.alive || []).length} alive · ${(g.soon || []).length} expiring · ${(g.expired || []).length} expired · ${g.point || 0} one-off</span></div>${alive}${renewals ? `<ul class="gov-list">${renewals}</ul>` : ''}${form}<p id="gov-msg" class="gov-note"></p>`;
+}
+
+const govSignals = (signals) => `<div class="section-header"><span class="section-header__title">Signals</span></div>${(signals || []).length ? `<ul class="gov-list">${signals.map((s) => `<li>⚠ ${esc(s)}</li>`).join('')}</ul>` : '<p class="gov-note">None.</p>'}`;

package/packages/hu-board/src/auth.js

@@ -20,6 +20,8 @@
  *     legacy callers keep working.
  */
 
+import { timingSafeEqual } from "node:crypto";
+
 /** Loopback addresses we trust without auth, regardless of token state. */
 const LOOPBACK_ADDRESSES = new Set([
   "127.0.0.1",
@@ -41,7 +43,7 @@ export function authMiddleware() {
     if (isLoopback(req)) return next();
 
     const token = extractToken(req);
-    if (token === expected) return next();
+    if (tokensMatch(token, expected)) return next();
 
     return res.status(401).json({
       error: "Unauthorized",
@@ -53,6 +55,32 @@ export function authMiddleware() {
   };
 }
 
+/**
+ * Constant-time comparison of a presented token against the expected one.
+ *
+ * `===` on strings stops at the first differing byte, so the time it takes to
+ * reject a token leaks how much of a correct prefix was supplied. Over the
+ * loopback interface that is noise — but this middleware exists precisely for
+ * the case the header above describes, where the board is bound beyond
+ * loopback and the peer is on the LAN. There the difference is measurable, and
+ * the token can be recovered a byte at a time.
+ *
+ * `timingSafeEqual` throws when the buffers differ in length, so the length is
+ * checked first. That is not a leak worth closing: the length of the expected
+ * token is fixed by whatever wrote `~/.karajan/hu-board/token`, and a token of
+ * the wrong length is wrong regardless of its contents.
+ *
+ * @param {string|undefined} presented
+ * @param {string} expected
+ * @returns {boolean}
+ */
+function tokensMatch(presented, expected) {
+  if (typeof presented !== "string") return false;
+  const left = Buffer.from(presented, "utf8");
+  const right = Buffer.from(expected, "utf8");
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
 /**
  * @param {import('express').Request} req
  * @returns {boolean}

package/packages/hu-board/src/routes/governance.js

@@ -0,0 +1,140 @@
+// GUI-A (KJC-TSK-0771, epic KJC-PCS-0076) — governance snapshot of ONE
+// project for the dashboard: the declared policy, the deterministic report
+// (`kj policy report --json`), the anchor state and the clone's declared
+// identity. The board stays decoupled from the CLI tree (KJC-TSK-0632): the
+// report comes from the kj binary, everything else is read from the
+// project's .karajan/ files. Read-only; actions land in GUI-C.
+import { Router } from "express";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import yaml from "js-yaml";
+import { runCommand } from "karajan-core/process";
+
+const router = Router();
+
+const readYaml = (file) => {
+  if (!existsSync(file)) return { found: false, data: null, error: null };
+  try { return { found: true, data: yaml.load(readFileSync(file, "utf8")), error: null }; }
+  catch (err) { return { found: true, data: null, error: String(err.message || err) }; }
+};
+
+/** policy.yml → flat rules the view can list (rule ids match the engine's). */
+function policySummary(dir) {
+  const { found, data, error } = readYaml(join(dir, ".karajan", "policy.yml"));
+  if (!found) return { declared: false, rules: [], invariants: [], error: null };
+  if (error || !data || typeof data !== "object") return { declared: true, rules: [], invariants: [], error: error || "policy.yml is not a mapping" };
+  const rules = [];
+  for (const [role, caps] of Object.entries(data.roles || {})) {
+    for (const [cap, spec] of Object.entries(caps || {})) {
+      if (!spec || typeof spec !== "object") continue;
+      for (const kind of ["deny", "allow"]) {
+        if (Array.isArray(spec[kind])) rules.push({ rule_id: `roles.${role}.${cap}.${kind}`, role, cap, kind, patterns: spec[kind], enforcement: spec.enforcement || "warn", class: spec.class || null });
+      }
+    }
+  }
+  const invariants = (Array.isArray(data.invariants) ? data.invariants : []).map((i) => ({ ...i, enforcement: i?.enforcement || "warn" }));
+  return { declared: true, version: data.version ?? null, rules, invariants, error: null };
+}
+
+function anchorState(dir, chainLength) {
+  const file = join(dir, ".karajan", "policy-anchor.json");
+  if (!existsSync(file)) return { sealed: false, length: 0, current: chainLength, stale: chainLength > 0 };
+  try {
+    const a = JSON.parse(readFileSync(file, "utf8"));
+    const length = Number(a.length) || 0;
+    return { sealed: true, head: a.head ?? null, ts: a.ts ?? null, length, current: chainLength, stale: chainLength !== length };
+  } catch (err) { return { sealed: false, length: 0, current: chainLength, stale: true, error: String(err.message || err) }; }
+}
+
+function identityState(dir) {
+  const { found, data } = readYaml(join(dir, ".karajan", "identity.local.yml"));
+  const ok = found && data && typeof data === "object" && data.gh_user && data.git_email;
+  return ok ? { declared: true, gh_user: String(data.gh_user), git_email: String(data.git_email) } : { declared: false };
+}
+
+/** The board may run from a package inside a monorepo: climb to the nearest .karajan/. */
+function nearestProject(start) {
+  let cur = resolve(start);
+  for (;;) {
+    if (existsSync(join(cur, ".karajan"))) return cur;
+    const up = resolve(cur, "..");
+    if (up === cur) return resolve(start);
+    cur = up;
+  }
+}
+
+router.get("/", async (req, res) => {
+  // GUI-B: without dir, the project the board was started for (same rule as
+  // the config editor: KJ_PROJECT_DIR || cwd) — the view remembers the rest.
+  const raw = (typeof req.query.dir === "string" && req.query.dir.trim()) || nearestProject(process.env.KJ_PROJECT_DIR || process.cwd());
+  const dir = resolve(raw);
+  if (!existsSync(join(dir, ".karajan")) || !statSync(join(dir, ".karajan")).isDirectory()) {
+    // Data, not a server error: the view shows the attempted dir and lets the user fix it.
+    return res.json({ ok: false, error: "not a karajan project: no .karajan/ directory", dir });
+  }
+  let report;
+  try {
+    // exit 1 = broken chain: the JSON still carries chain.ok=false — data, not a server error.
+    const r = await runCommand("kj", ["policy", "report", "--json"], { cwd: dir });
+    if (r.exitCode === 127) return res.status(503).json({ ok: false, error: "kj not installed", installable: true });
+    const line = String(r.stdout || "").trim().split("\n").findLast((l) => l.startsWith("{"));
+    report = line ? JSON.parse(line) : null;
+    if (!report) return res.status(502).json({ ok: false, error: "kj policy report produced no JSON", exitCode: r.exitCode, stderr: String(r.stderr || "").slice(0, 500) });
+  } catch (err) {
+    if (err?.code === "ENOENT") return res.status(503).json({ ok: false, error: "kj not installed", installable: true });
+    return res.status(500).json({ ok: false, error: String(err.message || err) });
+  }
+  res.json({ ok: true, dir, policy: policySummary(dir), report, anchor: anchorState(dir, report.chain?.length ?? 0), identity: identityState(dir) });
+});
+
+// GUI-C (KJC-TSK-0773): actions go through the SAME CLI commands the
+// terminal uses — the inexemptable (security, defaults.*) is refused by kj
+// itself and its message travels back verbatim; nothing is re-implemented.
+const projectOf = (req) => {
+  const raw = (typeof req.body?.dir === "string" && req.body.dir.trim()) || nearestProject(process.env.KJ_PROJECT_DIR || process.cwd());
+  const dir = resolve(raw);
+  return existsSync(join(dir, ".karajan")) ? dir : null;
+};
+
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+
+async function runKj(res, dir, args) {
+  try {
+    const r = await runCommand("kj", args, { cwd: dir });
+    // kj logs with colours; the board shows text (ESC built by code: no control char in a regex literal).
+    const output = `${r.stdout || ""}${r.stderr || ""}`.replaceAll(ANSI, "").trim();
+    if (r.exitCode === 127) return res.status(503).json({ ok: false, error: "kj not installed", installable: true });
+    if (r.exitCode !== 0) return res.status(409).json({ ok: false, error: output || `kj exited ${r.exitCode}`, exitCode: r.exitCode });
+    return res.json({ ok: true, output });
+  } catch (err) {
+    if (err?.code === "ENOENT") return res.status(503).json({ ok: false, error: "kj not installed", installable: true });
+    return res.status(500).json({ ok: false, error: String(err.message || err) });
+  }
+}
+
+router.post("/grant", async (req, res) => {
+  const dir = projectOf(req);
+  if (!dir) return res.status(404).json({ ok: false, error: "not a karajan project" });
+  const { rule, until, reason } = req.body || {};
+  if (!rule || !until || !String(reason || "").trim()) return res.status(400).json({ ok: false, error: "rule, until (ISO) and reason are required — an exception without who/why/until is a hole" });
+  if (!identityState(dir).declared) return res.status(409).json({ ok: false, error: "identity not declared for this clone — run kj identity set first (the grant must be attributable)" });
+  return runKj(res, dir, ["policy", "grant", "--rule", String(rule), "--until", String(until), "--reason", String(reason).trim()]);
+});
+
+// Spoken rule: `kj policy add <text>` proposes the diff; ONLY apply:true adds
+// --yes. The engine validates the vocabulary; the human confirms in the board.
+router.post("/rule", async (req, res) => {
+  const dir = projectOf(req);
+  if (!dir) return res.status(404).json({ ok: false, error: "not a karajan project" });
+  const text = String(req.body?.text || "").trim();
+  if (!text) return res.status(400).json({ ok: false, error: "text is required — say the rule" });
+  return runKj(res, dir, ["policy", "add", text, ...(req.body?.apply === true ? ["--yes"] : [])]);
+});
+
+router.post("/anchor", async (req, res) => {
+  const dir = projectOf(req);
+  if (!dir) return res.status(404).json({ ok: false, error: "not a karajan project" });
+  return runKj(res, dir, ["policy", "anchor"]);
+});
+
+export default router;

package/packages/hu-board/src/server.js

@@ -10,6 +10,7 @@ import apiRoutes from './routes/api.js';
 import pipelineRoutes from './routes/pipeline.js';
 import ragRoutes from './routes/rag.js';
 import wikiRoutes from './routes/wiki.js';
+import governanceRoutes from './routes/governance.js';
 import { authMiddleware } from './auth.js';
 import { getOrCreateToken, getTokenPath } from './token-store.js';
 import { reapZombieSessions } from './zombie-reaper.js';
@@ -301,6 +302,7 @@ async function main() {
   app.use('/api/pipeline', authMiddleware(), pipelineRoutes);
   app.use('/api/rag', authMiddleware(), ragRoutes);
   app.use('/api/wiki', authMiddleware(), wikiRoutes);
+  app.use('/api/governance', authMiddleware(), governanceRoutes);
 
   // SPA fallback: serve index.html for non-API, non-static routes
   app.get('/{*splat}', (_req, res) => {

package/scripts/install.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { tomlPath } from "./toml-value.js";
 
 const rl = readline.createInterface({ input, output });
 const REGISTRY_PATH = path.join(os.homedir(), ".karajan", "instances.json");
@@ -259,10 +260,10 @@ async function setupCodexMcp({ rootDir, kjHome }) {
   const block = [
     '[mcp_servers."karajan-mcp"]',
     'command = "node"',
-    `args = ["${path.join(rootDir, "src", "mcp", "server.js")}"]`,
-    `cwd = "${rootDir}"`,
+    `args = [${tomlPath(path.join(rootDir, "src", "mcp", "server.js"))}]`,
+    `cwd = ${tomlPath(rootDir)}`,
     '[mcp_servers."karajan-mcp".env]',
-    `KJ_HOME = "${kjHome}"`
+    `KJ_HOME = ${tomlPath(kjHome)}`
   ].join("\n");
 
   const updated = upsertCodexMcpBlock(toml, block);

package/scripts/postinstall.js

@@ -11,6 +11,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { tomlPath } from "./toml-value.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(__dirname, "..");
@@ -92,10 +93,10 @@ async function setupCodexMcp(kjHome) {
   const block = [
     '[mcp_servers."karajan-mcp"]',
     'command = "node"',
-    `args = ["${path.join(ROOT_DIR, "src", "mcp", "server.js")}"]`,
-    `cwd = "${ROOT_DIR}"`,
+    `args = [${tomlPath(path.join(ROOT_DIR, "src", "mcp", "server.js"))}]`,
+    `cwd = ${tomlPath(ROOT_DIR)}`,
     '[mcp_servers."karajan-mcp".env]',
-    `KJ_HOME = "${kjHome}"`
+    `KJ_HOME = ${tomlPath(kjHome)}`
   ].join("\n");
 
   const updated = upsertCodexMcpBlock(toml, block);

package/scripts/toml-value.js

@@ -0,0 +1,18 @@
+/**
+ * A filesystem path as a TOML value (KJC-BUG-0151, issue #1426 from dfosela).
+ *
+ * In a double-quoted TOML string `\` opens an escape sequence, so a Windows
+ * path like `C:\Users\...` is not valid TOML: `\U` is read as a unicode escape.
+ * kj wrote the karajan-mcp block that way and codex then failed to load its
+ * ENTIRE config — `codex login` included. kj thought it had configured the MCP;
+ * what it had done was break a tool the user had not touched.
+ *
+ * A literal string (single quotes) interprets nothing, which is exactly what a
+ * path needs. Only a path containing a single quote falls back to the basic
+ * form, escaped properly — never left broken.
+ */
+export function tomlPath(value) {
+  const s = String(value);
+  if (!s.includes("'")) return `'${s}'`;
+  return `"${s.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}

package/src/audit/basal-cost.js

@@ -272,10 +272,14 @@ export async function saveAuditSnapshot(projectDir, metrics) {
 
 export function computeGrowthDelta(current, previous) {
   if (!previous) return null;
+  // AC8 (KJC-TSK-0794): "not measured before" must never read as "unchanged" —
+  // the derivative only exists when BOTH snapshots actually measured it.
+  const bothMeasured = Array.isArray(current.deadExports) && Array.isArray(previous.deadExports);
   return {
     lines: current.totalLines - previous.totalLines,
     files: current.totalFiles - previous.totalFiles,
     deps: current.dependencies.total - (previous.dependencies?.total ?? 0),
+    deadExports: bothMeasured ? current.deadExports.length - previous.deadExports.length : null,
     since: previous.timestamp || null
   };
 }