create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/hub-bridge-access.js

@@ -0,0 +1,798 @@
+'use strict';
+
+// WP-2 (docs/remote-session-hub-bridge-2026-10-30.html §5 R-4/R-5/R-8/R-9, the Rev-2 card R-11, §6.2,
+// §8 WP-2): the ACCESS DECISION for a hub-bridge op — may this caller session run this tier on THIS
+// machine, and if not, what does the hub tell the agent and the user?
+//
+//   R-4  grants, on TWO axes (docs/hub-bridge-approval-scopes-2026-11-01.html §5 D-1..D-5, §6.1).
+//        A grant is keyed (machineId, callerSessionId, tier) and covers only its own tier (`exec`
+//        implies `read`). SCOPE is one caller session, or every session of that machine written
+//        `callerSessionId: '*'` (ALL_SESSIONS). DURATION is a TTL in memory (default 3600 s, hard max
+//        28800 s — a restart revokes it) or `always: true`, persisted in the trust file's `grants`
+//        array so it survives a restart. Neither axis ever writes machine trust or the mesh (D-2).
+//        Minted only by a user principal (`POST /api/hub-bridge/grants`, lib/api/hub-bridge.js). To
+//        keep it testable the clock is INJECTED (`deps.now`), never read directly.
+//   R-5  requested, never ambient. A refusal at trust `ask` records ONE pending row per
+//        (machineId, callerSessionId, tier) — a second call while it is open adds no row and
+//        re-broadcasts nothing — and answers `hub_grant_required` with that row's id.
+//   R-11 trust policy per machine, set on the machine that does the work. `getDataDir()/hub-bridge-trust.json`
+//        (mode 0600, atomic tmp+rename) holds `{ v:1, default:'ask', machines:{ [instanceId]: 'ask'|'always'|'never' },
+//        grants:[ {machineId, callerSessionId, tier, at} ] }`. `always` is an implicit grant of every
+//        tier to every session of that member (audited, no TTL); `never` refuses with
+//        `hub_bridge_denied` and creates NO pending row; `ask` is the R-4 flow. `grants` holds the
+//        machine-scoped and durable grants of D-1/D-4 and is written ONLY by grant/revoke (a trust
+//        PUT carries it through untouched). The file is re-read per decision (mtime+size cached), so a
+//        change applies to the next call.
+//   R-9  audited. `argsDigest` is sha256(JSON(args)) and the RAW args are never written.
+//
+// Everything is injectable (`configure`) and the process singleton is wired once at boot in server.js.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { getDataDir } = require('./data-dir');
+
+const TRUST_FILE = 'hub-bridge-trust.json';
+const AUDIT_FILE = 'hub-bridge-audit.jsonl';
+const TRUST_VALUES = Object.freeze(['ask', 'always', 'never']);
+// The known tiers, ordered for display only. Coverage is NOT by rank: R-4 says `exec` implies `read`
+// and nothing else — a `browser` grant gives no shell, and an `exec` grant drives no browser
+// (IMPLIES below). "always covers every tier" (R-11) is the trust check in decide(), not a grant.
+const TIER_RANK = Object.freeze({ none: 0, read: 1, exec: 2, browser: 3 });
+const IMPLIES = Object.freeze({ read: ['read'], exec: ['exec', 'read'], browser: ['browser'] });
+const DEFAULT_TTL_SEC = 3600;
+const MAX_TTL_SEC = 28800;
+const SUMMARY_MAX = 120;
+const AUDIT_TAIL_BYTES = 256 * 1024;
+const AUDIT_DEFAULT_LIMIT = 20;
+const AUDIT_MAX_LIMIT = 200;
+const TRUST_FILE_MODE = 0o600;
+// D-3: the machine-scope sentinel. A grant (or a request) whose callerSessionId is ALL_SESSIONS
+// stands for "every session of that machine" on the wire, in memory and on disk. Real caller session
+// ids are UUIDs, so the sentinel can never collide with one — and decide() REFUSES a caller that
+// claims to be '*' or empty, so a box can never impersonate "all sessions".
+const ALL_SESSIONS = '*';
+
+let _deps = null;
+// pairKey -> Map<tier, expiresAtMs>. Grants are per-process (a restart revokes everything, R-4).
+const _grants = new Map();
+// pendingId -> row. At most one row per (machineId, callerSessionId, tier) — see PENDING_INDEX.
+const _pending = new Map();
+// `${machineId}\u0000${callerSessionId}\u0000${tier}` -> pendingId. This is what makes R-5's
+// "one row per ask" true without scanning.
+const _pendingIndex = new Map();
+// mtime+size cache for the trust file (R-11: re-read per decision, cheap when unchanged).
+let _trustCache = { file: '', mtimeMs: -1, size: -1, value: null };
+// Every trust-file write (trust PUTs AND the durable grants of D-4) runs through this one chain, so
+// two concurrent writers cannot both read the same "current" and lose one of the two rows.
+let _trustWriteChain = Promise.resolve();
+
+const DEFAULT_DEPS = {
+  now: () => Date.now(),
+  randomUUID: () => crypto.randomUUID(),
+  // (frame) => void — the hub browser fan-out (hub-bridge-pending). Absent in tests that only care
+  // about the decision.
+  broadcast: null,
+  dataDir: '',
+};
+
+function configure(deps = {}) {
+  _deps = { ...DEFAULT_DEPS, ...(deps || {}) };
+  return _deps;
+}
+
+function _d() {
+  return _deps || DEFAULT_DEPS;
+}
+
+function _dataDir() {
+  const injected = _d().dataDir;
+  try {
+    return path.resolve(String(injected || getDataDir()));
+  } catch {
+    // expected: an unresolvable data dir still yields a usable absolute path for the default.
+    return path.resolve(getDataDir());
+  }
+}
+
+/** The trust file's absolute path (R-11). */
+function trustPath() {
+  return path.join(_dataDir(), TRUST_FILE);
+}
+
+/** The audit log's absolute path (R-9). */
+function auditPath() {
+  return path.join(_dataDir(), AUDIT_FILE);
+}
+
+/** Ranks for the two tiers an op may declare, in ascending order (exported for the tests). */
+function tierRank(tier) {
+  return Object.prototype.hasOwnProperty.call(TIER_RANK, String(tier)) ? TIER_RANK[String(tier)] : -1;
+}
+
+function isValidTier(tier) {
+  return tierRank(tier) >= 0;
+}
+
+/** Does a grant of `grantTier` satisfy a request for `tier`? (R-4: only exec implies read.) */
+function covers(grantTier, tier) {
+  const implied = IMPLIES[String(grantTier)];
+  return Array.isArray(implied) && implied.includes(String(tier));
+}
+
+/** A refusal/validation failure as this module speaks it: the code rides the error, never the message. */
+function _namedError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+/**
+ * Fan one browser frame out (R-5's `hub-bridge-pending`, and its `-cleared` twin). Best-effort: a
+ * dead browser socket must never fail the decision that triggered the frame.
+ */
+function _broadcast(frame) {
+  const broadcast = _d().broadcast;
+  if (typeof broadcast !== 'function') return;
+  try {
+    broadcast(frame);
+  } catch {
+    // expected: the fan-out is best-effort — a dead browser socket must never fail a decision.
+  }
+}
+
+/**
+ * R-5/R-13: tell every browser which pending rows just went away, so a toolbar banner can hide
+ * without a re-read. Fires ONCE per removal batch and NEVER when nothing was removed.
+ * @param {string[]} ids the removed pending row ids
+ * @returns {boolean} whether a frame was broadcast
+ */
+function _broadcastCleared(ids) {
+  const list = (Array.isArray(ids) ? ids : []).map((id) => String(id || '')).filter(Boolean);
+  if (!list.length) return false;
+  _broadcast({ type: 'hub-bridge-pending-cleared', ids: list });
+  return true;
+}
+
+function _pairKey(machineId, callerSessionId) {
+  return `${machineId}\u0000${callerSessionId}`;
+}
+
+function _pendingKey(machineId, callerSessionId, tier) {
+  return `${machineId}\u0000${callerSessionId}\u0000${tier}`;
+}
+
+// ---------------------------------------------------------------------------------------------
+// R-11 — the trust file
+// ---------------------------------------------------------------------------------------------
+
+/** The one shape a persisted grant row may take, or null when the row is not one (D-4). */
+function _sanitizeGrantRow(row) {
+  if (!row || typeof row !== 'object') return null;
+  const machineId = String(row.machineId || '');
+  const callerSessionId = String(row.callerSessionId || '');
+  const tier = String(row.tier || '');
+  if (!machineId || !callerSessionId) return null;
+  if (!isValidTier(tier) || tier === 'none') return null;
+  return { machineId, callerSessionId, tier, at: Number(row.at) || 0 };
+}
+
+/** D-4's `grants`: keep the valid rows, drop exact (machineId, callerSessionId, tier) duplicates. */
+function _sanitizeGrants(input) {
+  const rows = Array.isArray(input) ? input : [];
+  const out = [];
+  const seen = new Set();
+  for (const raw of rows) {
+    const row = _sanitizeGrantRow(raw);
+    if (!row) continue;
+    const key = `${row.machineId}\u0000${row.callerSessionId}\u0000${row.tier}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(row);
+  }
+  return out;
+}
+
+/** Coerce anything read off disk (or off the wire) into the R-11 shape; unknown values collapse to ask. */
+function sanitizeTrust(input) {
+  const raw = input && typeof input === 'object' ? input : {};
+  const out = { v: 1, default: 'ask', machines: {}, grants: [] };
+  if (TRUST_VALUES.includes(raw.default)) out.default = raw.default;
+  const machines = raw.machines && typeof raw.machines === 'object' ? raw.machines : {};
+  for (const [id, value] of Object.entries(machines)) {
+    if (!id) continue;
+    if (TRUST_VALUES.includes(value)) out.machines[String(id)] = value;
+  }
+  out.grants = _sanitizeGrants(raw.grants);
+  return out;
+}
+
+/**
+ * The trust policy in force right now. Re-read per call, but only when the file's mtime/size changed
+ * (R-11: "the policy is read when each request is handled"). A missing or unreadable file is the
+ * documented default (`{v:1, default:'ask', machines:{}}`) — never a crash, never a silent 'always'.
+ */
+function readTrust() {
+  const file = trustPath();
+  let stat = null;
+  try {
+    stat = fs.statSync(file);
+  } catch {
+    stat = null; // expected: no trust file yet — the default policy applies
+  }
+  if (!stat) {
+    _trustCache = { file, mtimeMs: -1, size: -1, value: sanitizeTrust(null) };
+    return _trustCache.value;
+  }
+  if (_trustCache.file === file && _trustCache.mtimeMs === stat.mtimeMs && _trustCache.size === stat.size) {
+    return _trustCache.value;
+  }
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    text = ''; // REPORT via the default below: an unreadable trust file reads as 'ask' (fail to the ask flow, not to ambient trust)
+  }
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    parsed = null; // expected: a half-written or hand-broken file collapses to the default policy
+  }
+  const value = sanitizeTrust(parsed);
+  _trustCache = { file, mtimeMs: stat.mtimeMs, size: stat.size, value };
+  return value;
+}
+
+/** The trust value for one machine: its own row, else the file default (R-11). */
+function trustFor(machineId) {
+  const trust = readTrust();
+  const id = String(machineId || '');
+  const value = Object.prototype.hasOwnProperty.call(trust.machines, id) ? trust.machines[id] : trust.default;
+  return TRUST_VALUES.includes(value) ? value : 'ask';
+}
+
+/**
+ * Merge-and-write the trust policy atomically (tmp + rename, mode 0600). `patch.machines` is merged
+ * per id; a `null`/`''` value for an id REMOVES that id's row (back to the default). Values are
+ * validated against ask|always|never and a bad one rejects `trust_value_invalid` (the route answers
+ * 400). `patch.grants` is IGNORED: the durable grants of D-4 ride through untouched, so a trust PUT
+ * can neither add nor drop one (only grantGrants/revokeGrants write grants). Async: a write never
+ * runs on the hub's main loop (a loaded disk must not freeze the UI).
+ */
+async function writeTrust(patch = {}) {
+  const raw = patch && typeof patch === 'object' ? patch : {};
+  if (raw.default !== undefined && !TRUST_VALUES.includes(raw.default)) {
+    throw _namedError('trust_value_invalid', `default must be one of ${TRUST_VALUES.join('|')}`);
+  }
+  const incoming = raw.machines && typeof raw.machines === 'object' ? raw.machines : {};
+  for (const [id, value] of Object.entries(incoming)) {
+    if (!id || value === null || value === '') continue;
+    if (!TRUST_VALUES.includes(value)) {
+      throw _namedError('trust_value_invalid', `machines['${id}'] must be one of ${TRUST_VALUES.join('|')}`);
+    }
+  }
+  const next = await _chainTrustWrite(async () => {
+    const current = readTrust();
+    const machines = { ...current.machines };
+    for (const [id, value] of Object.entries(incoming)) {
+      if (!id) continue;
+      if (value === null || value === '') {
+        delete machines[id];
+        continue;
+      }
+      machines[id] = value;
+    }
+    const value = sanitizeTrust({
+      v: 1,
+      default: raw.default !== undefined ? raw.default : current.default,
+      machines,
+      // D-4: a trust PUT can never add or drop a grant — the durable rows ride through untouched.
+      grants: current.grants,
+    });
+    await _writeTrustFile(value);
+    return value;
+  });
+  _clearPendingTrusted();
+  return next;
+}
+
+/**
+ * Run one trust-file write at a time. The chain NEVER rejects (a failed write must not poison the
+ * queue for the writes behind it); the caller still sees its own rejection through the returned
+ * promise. Both writeTrust and the durable grants of D-4 go through here.
+ * @template T
+ * @param {() => Promise<T>} run
+ * @returns {Promise<T>}
+ */
+function _chainTrustWrite(run) {
+  const result = _trustWriteChain.then(run);
+  _trustWriteChain = result.then(() => {}, () => {});
+  return result;
+}
+
+/**
+ * Write the whole trust object atomically (tmp + rename, mode 0600) and become the cache's truth.
+ * Shared by writeTrust and the `always` grant writes, so both leave the exact same file on disk.
+ * @param {{v:number, default:string, machines:object, grants:Array}} next
+ */
+async function _writeTrustFile(next) {
+  const file = trustPath();
+  await fs.promises.mkdir(path.dirname(file), { recursive: true });
+  // G-5's spirit (no partial file ever visible): write a sibling tmp then rename over the target.
+  const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  await fs.promises.writeFile(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: TRUST_FILE_MODE });
+  await fs.promises.rename(tmp, file);
+  // The rename may keep the same mtime tick; trust the value we just wrote rather than the stat cache.
+  _trustCache = { file, mtimeMs: -1, size: -1, value: next };
+  return next;
+}
+
+/**
+ * A trust write that makes a machine 'always' has answered its open asks (the [Always allow] button, or
+ * the card select / page switch): drop them and broadcast ONE cleared frame, so no banner keeps asking.
+ */
+function _clearPendingTrusted() {
+  const cleared = [];
+  for (const [id, row] of [..._pending.entries()]) {
+    if (trustFor(row.machineId) !== 'always') continue;
+    _pending.delete(id);
+    _pendingIndex.delete(_pendingKey(row.machineId, row.callerSessionId, row.tier));
+    cleared.push(id);
+  }
+  _broadcastCleared(cleared);
+  return cleared.length > 0;
+}
+
+// ---------------------------------------------------------------------------------------------
+// R-4 — grants (D-1: one session or the whole machine × a TTL or `always`)
+// ---------------------------------------------------------------------------------------------
+
+/** D-1: the scope a callerSessionId names — '*' is every session of the machine. */
+function _scopeOf(callerSessionId) {
+  return callerSessionId === ALL_SESSIONS ? 'machine' : 'session';
+}
+
+/** D-1's wire/route shape of one grant row. */
+function _grantRow({ machineId, callerSessionId, tier, always, ttlSec, expiresAt }) {
+  return {
+    machineId,
+    callerSessionId,
+    tier,
+    scope: _scopeOf(callerSessionId),
+    always: always === true,
+    ttlSec: always === true ? null : ttlSec,
+    expiresAt: always === true ? null : expiresAt,
+  };
+}
+
+/** Does a durable (D-4) row for this exact pair cover `tier`? The trust file is the source of truth. */
+function _persistedGrant(machineId, callerSessionId, tier) {
+  return readTrust().grants.some((row) => row.machineId === machineId
+    && row.callerSessionId === callerSessionId
+    && covers(row.tier, tier));
+}
+
+function _clampTtlSec(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_TTL_SEC;
+  return Math.min(MAX_TTL_SEC, Math.max(1, Math.trunc(n)));
+}
+
+/** The live grant covering `tier` for this pair, or null. Expired rows are dropped as they are seen. */
+function _activeGrant(pairKey, tier) {
+  const byTier = _grants.get(pairKey);
+  if (!byTier) return null;
+  const nowMs = Number(_d().now()) || 0;
+  let found = null;
+  for (const [grantTier, expiresAt] of [...byTier.entries()]) {
+    if (!(Number(expiresAt) > nowMs)) {
+      byTier.delete(grantTier);
+      continue;
+    }
+    if (covers(grantTier, tier)) found = { tier: grantTier, expiresAt };
+  }
+  if (!byTier.size) _grants.delete(pairKey);
+  return found;
+}
+
+/**
+ * Mint (or refresh) a grant on both axes (D-1). `callerSessionId` is one session — or ALL_SESSIONS
+ * for every session of the machine.
+ *   - `always !== true`: an in-memory TTL grant as before. `ttlSec` defaults to 3600 and is capped at
+ *     28800 (R-4); a restart drops it.
+ *   - `always === true`: a durable row `{machineId, callerSessionId, tier, at}` appended to the trust
+ *     file (D-4) through the same atomic write as writeTrust, idempotent per triple; `ttlSec` is
+ *     ignored. It never touches `machines`, never calls the mesh, and survives a restart.
+ * Both clear the pending rows the grant answers (D-5) and broadcast ONE cleared frame.
+ * @returns {Promise<{machineId:string, callerSessionId:string, tier:string, scope:'session'|'machine',
+ *   always:boolean, ttlSec:number|null, expiresAt:number|null}>}
+ */
+async function grantGrants({ machineId, callerSessionId, tier, ttlSec, always } = {}) {
+  const id = String(machineId || '');
+  const session = String(callerSessionId || '');
+  const wanted = String(tier || '');
+  if (!id || !session) throw _namedError('grant_invalid', 'machineId and callerSessionId are required');
+  if (!isValidTier(wanted) || wanted === 'none') {
+    throw _namedError('grant_invalid', `tier must be one of ${Object.keys(TIER_RANK).filter((t) => t !== 'none').join('|')}`);
+  }
+  if (always === true) {
+    const at = Number(_d().now()) || 0;
+    await _chainTrustWrite(async () => {
+      const current = readTrust();
+      const rows = current.grants.slice();
+      const known = rows.some((row) => row.machineId === id && row.callerSessionId === session && row.tier === wanted);
+      if (!known) rows.push({ machineId: id, callerSessionId: session, tier: wanted, at });
+      return _writeTrustFile(sanitizeTrust({
+        v: 1,
+        default: current.default,
+        machines: current.machines,
+        grants: rows,
+      }));
+    });
+    _clearPending(id, session, wanted);
+    return _grantRow({ machineId: id, callerSessionId: session, tier: wanted, always: true });
+  }
+  const ttl = _clampTtlSec(ttlSec);
+  const expiresAt = (Number(_d().now()) || 0) + ttl * 1000;
+  const pairKey = _pairKey(id, session);
+  const byTier = _grants.get(pairKey) || new Map();
+  byTier.set(wanted, expiresAt);
+  _grants.set(pairKey, byTier);
+  _clearPending(id, session, wanted);
+  return _grantRow({ machineId: id, callerSessionId: session, tier: wanted, always: false, ttlSec: ttl, expiresAt });
+}
+
+/**
+ * Drop every pending row this grant answers (D-5). A machine-scoped grant (callerSessionId ===
+ * ALL_SESSIONS) answers every session of that machine; otherwise the match is the strict pair.
+ */
+function _clearPending(machineId, callerSessionId, grantedTier) {
+  const everySession = callerSessionId === ALL_SESSIONS;
+  const cleared = [];
+  for (const [id, row] of [..._pending.entries()]) {
+    if (row.machineId !== machineId) continue;
+    if (!everySession && row.callerSessionId !== callerSessionId) continue;
+    if (!covers(grantedTier, row.tier)) continue;
+    _pending.delete(id);
+    _pendingIndex.delete(_pendingKey(row.machineId, row.callerSessionId, row.tier));
+    cleared.push(id);
+  }
+  // R-13: one frame per removal batch, and none at all when the grant answered no open ask.
+  _broadcastCleared(cleared);
+  return cleared.length > 0;
+}
+
+/**
+ * Revoke grants for a pair. With no `tier`, every tier is dropped; with one, that tier and every
+ * grant that covers it is dropped (revoking `read` also drops `exec`, matching how a grant is honoured).
+ * Both the in-memory TTL rows and the durable rows of D-4 go — the trust file is rewritten ONLY when
+ * a durable row was actually removed, so revoking an hour grant never touches the disk.
+ * @returns {Promise<number>} how many grant rows were removed (both kinds together)
+ */
+async function revokeGrants({ machineId, callerSessionId, tier } = {}) {
+  const id = String(machineId || '');
+  const session = String(callerSessionId || '');
+  const wanted = String(tier || '');
+  const pairKey = _pairKey(id, session);
+  const byTier = _grants.get(pairKey);
+  let removed = 0;
+  if (byTier) {
+    for (const grantTier of [...byTier.keys()]) {
+      if (!wanted || covers(grantTier, wanted)) {
+        byTier.delete(grantTier);
+        removed += 1;
+      }
+    }
+    if (!byTier.size) _grants.delete(pairKey);
+  }
+  const persisted = await _chainTrustWrite(async () => {
+    const current = readTrust();
+    const kept = [];
+    let dropped = 0;
+    for (const row of current.grants) {
+      if (row.machineId === id && row.callerSessionId === session && (!wanted || covers(row.tier, wanted))) {
+        dropped += 1;
+        continue;
+      }
+      kept.push(row);
+    }
+    if (!dropped) return 0;
+    await _writeTrustFile(sanitizeTrust({
+      v: 1,
+      default: current.default,
+      machines: current.machines,
+      grants: kept,
+    }));
+    return dropped;
+  });
+  return removed + persisted;
+}
+
+/**
+ * Every live grant: the in-memory TTL rows as before, plus the durable rows of D-4 (`always:true`,
+ * `ttlSec`/`expiresAt` null, read straight off the trust file). Sort (D-1's display order): machine,
+ * then session rows before the '*' machine rows, then callerSessionId, then tier rank, then `always`
+ * last inside a triple.
+ */
+function listGrants() {
+  const nowMs = Number(_d().now()) || 0;
+  const rows = [];
+  for (const byTier of _grants.values()) {
+    for (const [tier, expiresAt] of [...byTier.entries()]) {
+      if (!(Number(expiresAt) > nowMs)) byTier.delete(tier);
+    }
+  }
+  for (const [pairKey, byTier] of [..._grants.entries()]) {
+    if (!byTier.size) {
+      _grants.delete(pairKey);
+      continue;
+    }
+    const [machineId, callerSessionId] = pairKey.split('\u0000');
+    for (const [tier, expiresAt] of byTier.entries()) {
+      rows.push({
+        machineId,
+        callerSessionId,
+        tier,
+        scope: _scopeOf(callerSessionId),
+        always: false,
+        ttlSec: Math.max(0, Math.round((expiresAt - nowMs) / 1000)),
+        expiresAt,
+      });
+    }
+  }
+  for (const row of readTrust().grants) {
+    rows.push(_grantRow({ ...row, always: true }));
+  }
+  rows.sort((a, b) => (a.machineId.localeCompare(b.machineId)
+    || (a.scope === b.scope ? 0 : a.scope === 'session' ? -1 : 1)
+    || a.callerSessionId.localeCompare(b.callerSessionId)
+    || tierRank(a.tier) - tierRank(b.tier)
+    || (a.always === b.always ? 0 : a.always ? 1 : -1)));
+  return rows;
+}
+
+// ---------------------------------------------------------------------------------------------
+// R-5 — pending asks
+// ---------------------------------------------------------------------------------------------
+
+/** The one-line human summary an ask carries: the first 120 chars of the command or path. */
+function summarizeArgs(args) {
+  const raw = args && typeof args === 'object' ? args : {};
+  const text = String(raw.command || raw.path || raw.ref || '').replace(/\s+/g, ' ').trim();
+  return text.slice(0, SUMMARY_MAX);
+}
+
+/**
+ * Create or REUSE the single pending row for (machineId, callerSessionId, tier) and broadcast it
+ * ONLY when it is new (R-5: an agent polling in a loop must not spam the toolbar).
+ */
+function _requestPending({ machineId, callerSessionId, tier, op, machineName, summary }) {
+  const key = _pendingKey(machineId, callerSessionId, tier);
+  const existingId = _pendingIndex.get(key);
+  if (existingId && _pending.has(existingId)) return _pending.get(existingId);
+  const row = {
+    id: _d().randomUUID(),
+    machineId,
+    machineName: String(machineName || ''),
+    callerSessionId,
+    tier,
+    op: String(op || ''),
+    summary: String(summary || '').slice(0, SUMMARY_MAX),
+    at: Number(_d().now()) || 0,
+  };
+  _pending.set(row.id, row);
+  _pendingIndex.set(key, row.id);
+  _broadcast({ type: 'hub-bridge-pending', pending: row });
+  return row;
+}
+
+function listPending({ machineId } = {}) {
+  const rows = [..._pending.values()];
+  const id = String(machineId || '');
+  return (id ? rows.filter((row) => row.machineId === id) : rows).map((row) => ({ ...row }));
+}
+
+/** Clear one pending ask (the toolbar's Deny). Returns whether a row was actually removed. */
+function denyPending(id) {
+  const key = String(id || '');
+  const row = _pending.get(key);
+  if (!row) return false;
+  _pending.delete(key);
+  _pendingIndex.delete(_pendingKey(row.machineId, row.callerSessionId, row.tier));
+  // R-13: the toolbar hides this row's banner on the frame, not on a re-read.
+  _broadcastCleared([key]);
+  return true;
+}
+
+// ---------------------------------------------------------------------------------------------
+// R-9 — audit
+// ---------------------------------------------------------------------------------------------
+
+/** sha256(JSON(args)) — the ONLY form of the args that ever reaches disk (R-9). */
+function digestArgs(args) {
+  let text;
+  try {
+    text = JSON.stringify(args === undefined ? null : args);
+  } catch {
+    text = '"[unserialisable]"';
+  }
+  return crypto.createHash('sha256').update(String(text), 'utf8').digest('hex');
+}
+
+// Appends are chained so lines land in call order without a sync write on the main loop.
+let _auditChain = Promise.resolve();
+
+/** Resolves once every audit line queued so far is on disk (recentAudit and the tests await it). */
+function flushAudit() {
+  return _auditChain;
+}
+
+/**
+ * Queue one JSONL audit line and return the row. `entry.args` is digested here and never written;
+ * every other field is copied verbatim. Best-effort: a failed write must never fail the op it
+ * describes.
+ */
+function audit(entry = {}) {
+  const row = {
+    at: Number(entry.at) || Number(_d().now()) || 0,
+    machineId: String(entry.machineId || ''),
+    callerSessionId: String(entry.callerSessionId || ''),
+    op: String(entry.op || ''),
+    tier: String(entry.tier || 'none'),
+    via: String(entry.via || 'none'),
+    argsDigest: digestArgs(entry.args),
+    ok: entry.ok === true,
+    code: String(entry.code || ''),
+    ms: Math.max(0, Number(entry.ms) || 0),
+  };
+  const file = auditPath();
+  const line = `${JSON.stringify(row)}\n`;
+  _auditChain = _auditChain
+    .then(() => fs.promises.mkdir(path.dirname(file), { recursive: true }))
+    .then(() => fs.promises.appendFile(file, line))
+    .catch(() => {
+      // expected: the audit sink is best-effort (R-9) — a full disk must not fail a granted op.
+    });
+  return row;
+}
+
+/**
+ * The newest audit rows for one machine, newest first, from at most the last 256 KiB of the file.
+ * A line that straddles the read window (or is torn) is dropped rather than surfacing as garbage.
+ */
+async function recentAudit({ machineId, limit = AUDIT_DEFAULT_LIMIT } = {}) {
+  await flushAudit();
+  const file = auditPath();
+  const cap = Math.min(AUDIT_MAX_LIMIT, Math.max(1, Math.trunc(Number(limit) || AUDIT_DEFAULT_LIMIT)));
+  let handle = null;
+  let text = '';
+  let startedMidFile = false;
+  try {
+    handle = await fs.promises.open(file, 'r');
+    const stat = await handle.stat();
+    const start = Math.max(0, stat.size - AUDIT_TAIL_BYTES);
+    startedMidFile = start > 0;
+    const length = stat.size - start;
+    if (length <= 0) return [];
+    const buffer = Buffer.alloc(length);
+    await handle.read(buffer, 0, length, start);
+    text = buffer.toString('utf8');
+  } catch {
+    // REPORT via []: no audit file yet (or an unreadable one) is an empty history, not an error.
+    return [];
+  } finally {
+    if (handle) {
+      try { await handle.close(); } catch { /* expected: already closed */ }
+    }
+  }
+  const lines = text.split('\n');
+  if (startedMidFile) lines.shift(); // the first line may be a fragment of a row above the window
+  const wanted = String(machineId || '');
+  const rows = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let parsed = null;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue; // expected: a torn trailing line (another writer mid-append) is skipped
+    }
+    if (wanted && String(parsed.machineId || '') !== wanted) continue;
+    rows.push(parsed);
+  }
+  rows.reverse(); // newest first
+  return rows.slice(0, cap);
+}
+
+// ---------------------------------------------------------------------------------------------
+// The decision
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * R-4/R-11/D-3/D-5: decide one request. Order is fixed (D-5): an invalid tier or a caller that claims
+ * to be "all sessions" is refused outright; then machine trust; then the four grant lookups (hour
+ * session, hour '*', durable session, durable '*'); then the ask. Every grant hit reports via 'grant'.
+ * Still SYNCHRONOUS — it rides the op's request path (the trust file's cached sync read is why).
+ *
+ * @param {{machineId:string, callerSessionId:string, tier:string, op?:string, machineName?:string,
+ *          args?:object, summary?:string}} request
+ * @returns {{allow:true, via:'trust'|'grant'|'none'} |
+ *           {allow:false, code:'hub_bridge_denied'} |
+ *           {allow:false, code:'hub_grant_required', pendingId:string, tier:string}}
+ */
+function decide(request = {}) {
+  const machineId = String(request.machineId || '');
+  const callerSessionId = String(request.callerSessionId || '');
+  const tier = String(request.tier || 'none');
+  if (!isValidTier(tier)) return { allow: false, code: 'hub_bridge_denied' };
+  if (tier === 'none') return { allow: true, via: 'none' };
+  // D-3: '*' is the machine-scope SENTINEL, never a caller. A box claiming it (or claiming nothing)
+  // is refused before any trust/grant read, and creates NO pending row — it can never impersonate
+  // "all sessions" and thereby answer somebody else's ask.
+  if (!callerSessionId || callerSessionId === ALL_SESSIONS) return { allow: false, code: 'hub_bridge_denied' };
+
+  const trust = trustFor(machineId);
+  if (trust === 'never') return { allow: false, code: 'hub_bridge_denied' };
+  if (trust === 'always') return { allow: true, via: 'trust' };
+
+  // D-5: this session's own hour grant, then the machine's hour grant, then the two durable kinds.
+  if (_activeGrant(_pairKey(machineId, callerSessionId), tier)) return { allow: true, via: 'grant' };
+  if (_activeGrant(_pairKey(machineId, ALL_SESSIONS), tier)) return { allow: true, via: 'grant' };
+  if (_persistedGrant(machineId, callerSessionId, tier)) return { allow: true, via: 'grant' };
+  if (_persistedGrant(machineId, ALL_SESSIONS, tier)) return { allow: true, via: 'grant' };
+
+  const pending = _requestPending({
+    machineId,
+    callerSessionId,
+    tier,
+    op: request.op,
+    machineName: request.machineName,
+    summary: request.summary !== undefined ? request.summary : summarizeArgs(request.args),
+  });
+  return { allow: false, code: 'hub_grant_required', pendingId: pending.id, tier };
+}
+
+function _resetForTests() {
+  _deps = null;
+  _grants.clear();
+  _pending.clear();
+  _pendingIndex.clear();
+  _trustCache = { file: '', mtimeMs: -1, size: -1, value: null };
+  _trustWriteChain = Promise.resolve();
+  _auditChain = Promise.resolve();
+}
+
+module.exports = {
+  TRUST_FILE,
+  AUDIT_FILE,
+  TRUST_VALUES,
+  ALL_SESSIONS,
+  TIER_RANK,
+  DEFAULT_TTL_SEC,
+  MAX_TTL_SEC,
+  SUMMARY_MAX,
+  AUDIT_TAIL_BYTES,
+  AUDIT_DEFAULT_LIMIT,
+  configure,
+  tierRank,
+  isValidTier,
+  covers,
+  trustPath,
+  auditPath,
+  sanitizeTrust,
+  readTrust,
+  trustFor,
+  writeTrust,
+  grantGrants,
+  revokeGrants,
+  listGrants,
+  summarizeArgs,
+  listPending,
+  denyPending,
+  digestArgs,
+  audit,
+  flushAudit,
+  recentAudit,
+  decide,
+  _resetForTests,
+};