@venturewild/workspace 0.3.6 → 0.3.8

package/server/src/skills.mjs

@@ -0,0 +1,213 @@
+// Skill discovery + the Powers-block curation store (§7/§8). There is NO native
+// "list commands" API in Claude Code, so we discover the user's skills the cleanest
+// way the design settled on: SCAN the skill directories and parse YAML frontmatter.
+//
+//   - project skills:  <workspace>/.claude/skills/<name>/SKILL.md
+//   - project commands: <workspace>/.claude/commands/<name>.md
+//   - user skills:     ~/.claude/skills/<name>/SKILL.md
+//
+// Precedence (per §2): project > user. The Powers block is USER-CURATED — we surface
+// what the user has (their own + a teammate's, both trusted by membership) with NO
+// VW-prescribed core forced. The "─ from Bazaar ─" zone stays empty/LOCKED until the
+// Shelf trust/provenance Class-D gate ships (a tap runs third-party instructions with
+// bypassPermissions), so this module never returns Bazaar skills.
+//
+// Invocation is NOT done here: a Powers tap injects `/<name>` as a chat message, which
+// Claude Code expands+runs headless (verified §2) — the same stdin path we already use.
+//
+// Curation (which skills are pinned/hidden + their order) lives under
+// ~/.wild-workspace/powers/ (CLAUDE.md #1 — never the synced repo, never localStorage).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// Bounds so a workspace stuffed with skills can't bloat the store/UI.
+const CAP = { skills: 80, name: 64, desc: 280 };
+
+// --- frontmatter parse -----------------------------------------------------
+// Minimal, dependency-free. We only need a few scalar keys; the description often
+// CONTAINS colons ("Usage: /foo"), so we split on the FIRST colon only. Never throws.
+
+export function parseFrontmatter(text = '') {
+  const out = {};
+  if (typeof text !== 'string') return out;
+  // Frontmatter is the block between the first two `---` fences at the top.
+  const m = text.match(/^?---\s*\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return out;
+  for (const rawLine of m[1].split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const i = line.indexOf(':');
+    if (i < 0) continue;
+    const key = line.slice(0, i).trim();
+    let val = line.slice(i + 1).trim();
+    // strip matching surrounding quotes
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+function asBool(v, dflt) {
+  if (v === undefined) return dflt;
+  const s = String(v).trim().toLowerCase();
+  if (s === 'true' || s === 'yes' || s === '1') return true;
+  if (s === 'false' || s === 'no' || s === '0') return false;
+  return dflt;
+}
+
+function clip(s, n) {
+  return String(s || '').slice(0, n);
+}
+
+// Build one skill record from a parsed frontmatter + its fallback name.
+function toSkill(fm, fallbackName, source) {
+  const name = clip(fm.name || fallbackName, CAP.name).trim();
+  if (!name) return null;
+  return {
+    name,
+    description: clip(fm.description || '', CAP.desc).trim(),
+    source, //                       'project' | 'user'
+    // user-invocable defaults TRUE (most skills can be run as /name); only an explicit
+    // `user-invocable: false` opts out of being a tappable Power.
+    userInvocable: asBool(fm['user-invocable'], true),
+  };
+}
+
+function readFileSafe(file) {
+  try { return fs.readFileSync(file, 'utf8'); } catch { return null; }
+}
+
+function listDirs(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch { return []; }
+}
+
+function listFiles(dir, ext) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith(ext))
+      .map((e) => e.name);
+  } catch { return []; }
+}
+
+// Scan one skills root (<root>/<name>/SKILL.md) → skill records.
+function scanSkillsRoot(root, source) {
+  const out = [];
+  for (const name of listDirs(root)) {
+    const text = readFileSafe(path.join(root, name, 'SKILL.md'));
+    if (text == null) continue;
+    const s = toSkill(parseFrontmatter(text), name, source);
+    if (s) out.push(s);
+  }
+  return out;
+}
+
+// Scan a commands root (<root>/<name>.md) → skill records.
+function scanCommandsRoot(root, source) {
+  const out = [];
+  for (const file of listFiles(root, '.md')) {
+    const text = readFileSafe(path.join(root, file));
+    if (text == null) continue;
+    const s = toSkill(parseFrontmatter(text), file.replace(/\.md$/, ''), source);
+    if (s) out.push(s);
+  }
+  return out;
+}
+
+/**
+ * Discover the workspace's skills. Project entries take precedence over same-named
+ * user entries (§2). Returns ONLY user-invocable skills (the Powers block taps run
+ * them as /name), capped. Never throws — a missing dir just yields fewer skills.
+ */
+export function discoverSkills({ workspaceDir = process.cwd(), home = os.homedir() } = {}) {
+  const project = [
+    ...scanSkillsRoot(path.join(workspaceDir, '.claude', 'skills'), 'project'),
+    ...scanCommandsRoot(path.join(workspaceDir, '.claude', 'commands'), 'project'),
+  ];
+  const user = scanSkillsRoot(path.join(home, '.claude', 'skills'), 'user');
+
+  // Dedup by name, project wins.
+  const byName = new Map();
+  for (const s of user) byName.set(s.name, s);
+  for (const s of project) byName.set(s.name, s); // overrides user
+  return [...byName.values()]
+    .filter((s) => s.userInvocable)
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .slice(0, CAP.skills);
+}
+
+// --- curation store --------------------------------------------------------
+// The user's arrangement: `order` (pinned, in display order) + `hidden` (subtracted).
+// A discovered skill not in either is shown after the pinned ones (so a NEW skill
+// appears without the user having to add it — "add/subtract/arrange", subtract is opt-in).
+
+export function defaultPowersDir(env = process.env, home = os.homedir()) {
+  const base = env.WILD_WORKSPACE_GLOBAL_DIR || path.join(home, '.wild-workspace');
+  return path.join(base, 'powers');
+}
+
+function readJsonSafe(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+}
+
+export function createPowers({ baseDir, workspaceDir, home = os.homedir(), env = process.env } = {}) {
+  const dir = baseDir || defaultPowersDir(env, home);
+  const curationFile = path.join(dir, 'curation.json');
+
+  function getCuration() {
+    const v = readJsonSafe(curationFile, null);
+    const order = Array.isArray(v?.order) ? v.order.filter((s) => typeof s === 'string') : [];
+    const hidden = Array.isArray(v?.hidden) ? v.hidden.filter((s) => typeof s === 'string') : [];
+    return { order, hidden };
+  }
+
+  function saveCuration(raw = {}) {
+    const order = Array.isArray(raw.order)
+      ? [...new Set(raw.order.filter((s) => typeof s === 'string').map((s) => s.slice(0, CAP.name)))].slice(0, CAP.skills)
+      : [];
+    const hidden = Array.isArray(raw.hidden)
+      ? [...new Set(raw.hidden.filter((s) => typeof s === 'string').map((s) => s.slice(0, CAP.name)))].slice(0, CAP.skills)
+      : [];
+    const data = { order, hidden, ts: Date.now() };
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      const tmp = `${curationFile}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+      fs.renameSync(tmp, curationFile);
+    } catch { /* read-only fs — degrade to not-persisted */ }
+    return data;
+  }
+
+  // The merged view the UI renders: discovered skills, ordered by curation, with a
+  // `hidden` flag. Pinned (in `order`) first, then the rest alphabetically.
+  function state() {
+    const discovered = discoverSkills({ workspaceDir, home });
+    const { order, hidden } = getCuration();
+    const hiddenSet = new Set(hidden);
+    const rank = new Map(order.map((n, i) => [n, i]));
+    const skills = discovered
+      .map((s) => ({ ...s, hidden: hiddenSet.has(s.name) }))
+      .sort((a, b) => {
+        const ra = rank.has(a.name) ? rank.get(a.name) : Infinity;
+        const rb = rank.has(b.name) ? rank.get(b.name) : Infinity;
+        if (ra !== rb) return ra - rb;
+        return a.name.localeCompare(b.name);
+      });
+    return {
+      skills,
+      curation: { order, hidden },
+      // The marketplace zone is specified but GATED (Class-D, not built) — always
+      // empty + locked here so the UI can render the "─ from Bazaar ─" boundary.
+      bazaar: { locked: true, skills: [] },
+    };
+  }
+
+  return { dir, curationFile, getCuration, saveCuration, state };
+}

package/server/src/usage.mjs

@@ -0,0 +1,405 @@
+// Usage + context service — the data behind the floating "Usage" canvas block (§8 of
+// docs/agent-engine-and-commands-design.md). Two numbers, two sources:
+//
+//   1. Plan utilization (Session 5-hour + Weekly 7-day %)  — AUTHORITATIVE, from
+//      Anthropic's own OAuth usage endpoint. The same endpoint ccstatusline reads.
+//   2. Context % ("working memory")                        — LOCAL, computed from the
+//      latest assistant turn's token usage (no network). See computeContext().
+//
+// DESIGN RULES baked in here (don't relitigate — see §8):
+//   - The endpoint is UNOFFICIAL/community-documented → we DEGRADE, never throw. A
+//     failure keeps the last-good value and flips status to 'stale'/'unavailable';
+//     the UI shows that honestly. Core UX never depends on it.
+//   - `User-Agent: claude-code/<version>` is MANDATORY — omitting it is a hard 429.
+//   - Poll every 60–120s and ALWAYS re-poll: utilization climbs WITHIN a window as the
+//     user consumes, so `resets_at` only drives the countdown + a post-reset refresh —
+//     it never suppresses polling.
+//   - On 429, back off (don't hammer) and serve stale.
+//   - We READ the user's Claude OAuth token locally (new trust surface). It only ever
+//     leaves the box to api.anthropic.com — never logged, never sent elsewhere. A
+//     one-time disclosure (stored ack under ~/.wild-workspace) gates first activation.
+//
+// VERIFIED EMPIRICALLY (2026-06-11, this box, `claude` 2.1.172):
+//   - ~/.claude/.credentials.json = { claudeAiOauth: { accessToken, expiresAt, … } }.
+//   - A real turn's usage: input_tokens=2, cache_creation_input_tokens=45504 → an
+//     input-only context gauge reads ~20× too low. Numerator = sum of the three.
+//   - Records store the model as `claude-opus-4-8` with the `[1m]` suffix STRIPPED, so
+//     a 1M-context session can't be distinguished from 200k by model name alone — the
+//     window map below defaults accordingly; see WINDOW_CALIBRATION note.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+
+const USAGE_ENDPOINT = 'https://api.anthropic.com/api/oauth/usage';
+const OAUTH_BETA = 'oauth-2025-04-20';
+
+// Poll cadence. The TTL *is* the cadence — we re-poll on it (see header). Kept in the
+// 60–120s band the design fixed (rate-limit-friendly); default 90s.
+export const DEFAULT_POLL_MS = 90_000;
+// After a transient 429 we back off to this before the next attempt.
+export const BACKOFF_MS = 5 * 60_000;
+// Per-request network timeout — never let a hung socket stall the timer.
+const FETCH_TIMEOUT_MS = 10_000;
+
+// --- credential resolution -------------------------------------------------
+// Order (per §8): CLAUDE_CONFIG_DIR → ~/.claude/.credentials.json → macOS keychain.
+// Returns { token, expiresAt } or null. Never throws (degrade).
+
+function readCredsFile(file) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const o = raw.claudeAiOauth || raw; // tolerate both shapes
+    const token = o.accessToken || o.access_token;
+    if (typeof token !== 'string' || !token) return null;
+    const expiresAt = o.expiresAt ?? o.expires_at ?? null;
+    return { token, expiresAt };
+  } catch {
+    return null;
+  }
+}
+
+function readKeychain() {
+  // macOS only. `security` returns the secret on stdout; any failure → null. The
+  // secret name follows Claude Code's convention ("Claude Code-credentials").
+  try {
+    const out = execFileSync(
+      'security',
+      ['find-generic-password', '-s', 'Claude Code-credentials', '-w'],
+      { encoding: 'utf8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    const raw = JSON.parse(out.trim());
+    const o = raw.claudeAiOauth || raw;
+    const token = o.accessToken || o.access_token;
+    if (typeof token !== 'string' || !token) return null;
+    return { token, expiresAt: o.expiresAt ?? o.expires_at ?? null };
+  } catch {
+    return null;
+  }
+}
+
+export function readOAuthToken({
+  env = process.env,
+  platform = process.platform,
+  home = os.homedir(),
+} = {}) {
+  // 1. CLAUDE_CONFIG_DIR/.credentials.json
+  const configDir = env.CLAUDE_CONFIG_DIR;
+  if (configDir) {
+    const hit = readCredsFile(path.join(configDir, '.credentials.json'));
+    if (hit) return hit;
+  }
+  // 2. ~/.claude/.credentials.json
+  const hit = readCredsFile(path.join(home, '.claude', '.credentials.json'));
+  if (hit) return hit;
+  // 3. macOS keychain
+  if (platform === 'darwin') {
+    const kc = readKeychain();
+    if (kc) return kc;
+  }
+  return null;
+}
+
+// True when a token is present but already past its expiry. v1 does NOT refresh
+// tokens (out of scope) — an expired token degrades to 'unavailable' so the user
+// is told honestly rather than seeing a silent 401 loop.
+export function isExpired(cred, now = Date.now()) {
+  if (!cred || cred.expiresAt == null) return false;
+  const exp = Number(cred.expiresAt);
+  if (!Number.isFinite(exp)) return false;
+  // expiresAt is epoch ms in the credentials file.
+  return exp <= now;
+}
+
+// --- claude version (for the mandatory UA) ---------------------------------
+// Best-effort, detected once and cached. The `claude-code/` PREFIX is what the
+// endpoint requires (omit → 429); the exact version is cosmetic, so a sane fallback
+// is fine if detection fails. Override via WILD_WORKSPACE_CLAUDE_VERSION (tests do).
+
+let _versionCache;
+export function claudeVersion(env = process.env) {
+  if (env.WILD_WORKSPACE_CLAUDE_VERSION) return env.WILD_WORKSPACE_CLAUDE_VERSION;
+  if (_versionCache !== undefined) return _versionCache;
+  try {
+    const out = execFileSync('claude', ['--version'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const m = out.match(/(\d+\.\d+\.\d+)/);
+    _versionCache = m ? m[1] : '2.1.172';
+  } catch {
+    _versionCache = '2.1.172'; // recent known-good fallback
+  }
+  return _versionCache;
+}
+
+export function userAgent(env = process.env) {
+  return `claude-code/${claudeVersion(env)}`;
+}
+
+// --- the network call ------------------------------------------------------
+// Returns { ok:true, status, body } on a 2xx with JSON, else { ok:false, status,
+// error }. NEVER throws — the caller's degrade logic keys off the shape.
+
+export async function fetchUsage({
+  token,
+  ua,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = FETCH_TIMEOUT_MS,
+} = {}) {
+  if (!token) return { ok: false, status: 0, error: 'no_token' };
+  if (typeof fetchImpl !== 'function') return { ok: false, status: 0, error: 'no_fetch' };
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(USAGE_ENDPOINT, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'anthropic-beta': OAUTH_BETA,
+        'User-Agent': ua, //                          ← MANDATORY (omit → hard 429)
+        'Content-Type': 'application/json',
+      },
+      signal: ctrl.signal,
+    });
+    if (!res.ok) return { ok: false, status: res.status, error: `http_${res.status}` };
+    const body = await res.json();
+    return { ok: true, status: res.status, body };
+  } catch (e) {
+    return { ok: false, status: 0, error: e?.name === 'AbortError' ? 'timeout' : 'network' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// --- parse the usage body --------------------------------------------------
+// Tolerant: any missing block degrades to null/absent rather than throwing. Shape
+// (per §8): { five_hour, seven_day, seven_day_opus, seven_day_sonnet, extra_usage }.
+
+function pctBlock(b) {
+  if (!b || typeof b !== 'object') return null;
+  const u = Number(b.utilization);
+  return {
+    utilization: Number.isFinite(u) ? Math.max(0, Math.min(100, u)) : 0,
+    resets_at: typeof b.resets_at === 'string' ? b.resets_at : null,
+  };
+}
+
+export function parseUsage(body = {}) {
+  if (!body || typeof body !== 'object') body = {};
+  const out = {
+    five_hour: pctBlock(body.five_hour),
+    seven_day: pctBlock(body.seven_day),
+    seven_day_opus: pctBlock(body.seven_day_opus),
+    seven_day_sonnet: pctBlock(body.seven_day_sonnet),
+  };
+  const ex = body.extra_usage;
+  if (ex && typeof ex === 'object') {
+    out.extra_usage = {
+      is_enabled: !!ex.is_enabled,
+      monthly_limit: Number(ex.monthly_limit) || 0,
+      used_credits: Number(ex.used_credits) || 0,
+      utilization: Number.isFinite(Number(ex.utilization)) ? Number(ex.utilization) : 0,
+    };
+  }
+  return out;
+}
+
+// --- context gauge (LOCAL, no network) -------------------------------------
+//
+// WINDOW_CALIBRATION (the documented residual — see §8/§9):
+//   - Numerator = input + cache_creation + cache_read (verified; input-only is ~10–20×
+//     low because cache dominates the prompt).
+//   - Denominator = the model's context window. Records DON'T carry context_window_size
+//     and STRIP the `[1m]` suffix, so we map by model name + detect a `[1m]` suffix when
+//     the live stream-json provides one. The 1M variant therefore UNDER-detects from
+//     historical records (defaults to 200k) — acceptable for a "working memory" gauge,
+//     not an exact clone of Claude's /context. If we adopt Claude's statusline hook
+//     later, prefer its context_window_size over this map.
+//   - Residual #2: does /context measure toward the full window or the auto-compact
+//     threshold? We measure toward the FULL window (ccstatusline's convention) and label
+//     it "working memory", not Claude's exact %.
+
+const K = 1000;
+const DEFAULT_WINDOW = 200 * K;
+const ONE_M = 1000 * K;
+// Prefix → window. Keep claude + the glm-* models this workspace has seen; unknown →
+// DEFAULT_WINDOW. (Non-Claude models get NO plan-usage, but the context gauge still works.)
+const WINDOWS = [
+  ['claude-opus', 200 * K],
+  ['claude-sonnet', 200 * K],
+  ['claude-haiku', 200 * K],
+  ['claude-fable', 200 * K],
+  ['glm', 200 * K],
+];
+
+export function windowFor(model) {
+  if (!model || typeof model !== 'string') return DEFAULT_WINDOW;
+  const m = model.toLowerCase();
+  // 1M-context variants advertise themselves with a [1m] / -1m marker WHEN present.
+  if (m.includes('[1m]') || m.includes('-1m') || m.endsWith(':1m')) return ONE_M;
+  for (const [prefix, w] of WINDOWS) if (m.startsWith(prefix)) return w;
+  return DEFAULT_WINDOW;
+}
+
+export function computeContext(usage = {}, model = '') {
+  const input = Number(usage.input_tokens) || 0;
+  const cacheCreate = Number(usage.cache_creation_input_tokens) || 0;
+  const cacheRead = Number(usage.cache_read_input_tokens) || 0;
+  const used = input + cacheCreate + cacheRead;
+  const window = windowFor(model);
+  const pct = window > 0 ? Math.max(0, Math.min(100, (used / window) * 100)) : 0;
+  return { used, window, pct, model: model || null };
+}
+
+// --- disclosure ack (server-side, one-time per USER) -----------------------
+// Stored under ~/.wild-workspace/usage/ (CLAUDE.md #1 — never the synced workspace,
+// never localStorage which would be per-browser/device). One file, last-write-wins.
+
+function defaultUsageDir(env = process.env, home = os.homedir()) {
+  const base = env.WILD_WORKSPACE_GLOBAL_DIR || path.join(home, '.wild-workspace');
+  return path.join(base, 'usage');
+}
+
+// --- the stateful service --------------------------------------------------
+// One instance per server. Owns the cached snapshot, the poll timer, the degrade
+// logic, the local context gauge, and the disclosure ack. `onUpdate(state)` fires on
+// every snapshot change (the WS push path mirrors the bazaar meter — no client poll).
+
+export function createUsageService({
+  env = process.env,
+  platform = process.platform,
+  home = os.homedir(),
+  baseDir, //                      override the ack dir (tests)
+  fetchImpl = globalThis.fetch,
+  pollMs = DEFAULT_POLL_MS,
+  onUpdate = null,
+  now = () => Date.now(),
+} = {}) {
+  const dir = baseDir || defaultUsageDir(env, home);
+  const ackFile = path.join(dir, 'disclosure.json');
+
+  // status: 'loading' (never fetched) | 'live' (fresh good data) | 'stale' (had data,
+  // last refresh failed) | 'unavailable' (no token / expired / never got data).
+  let snap = {
+    status: 'loading',
+    plan: null, //                 parsed usage blocks (five_hour, seven_day, …)
+    context: null, //              { used, window, pct, model }
+    fetchedAt: null, //            ms of the last GOOD fetch
+    error: null, //                last error marker (for the UI's honest message)
+  };
+  let timer = null;
+  let backoffUntil = 0;
+
+  function emit() {
+    if (typeof onUpdate === 'function') {
+      try { onUpdate(snapshot()); } catch { /* a bad listener never breaks the timer */ }
+    }
+  }
+
+  // One refresh cycle. NEVER throws. Returns the new snapshot.
+  async function refresh() {
+    // Respect a 429 backoff window: serve stale, don't hammer.
+    if (now() < backoffUntil) {
+      if (snap.status === 'live') snap = { ...snap, status: 'stale', error: 'backoff' };
+      return snapshot();
+    }
+    const cred = readOAuthToken({ env, platform, home });
+    if (!cred) {
+      snap = { ...snap, status: 'unavailable', error: 'no_token' };
+      emit();
+      return snapshot();
+    }
+    if (isExpired(cred, now())) {
+      // v1 does not refresh tokens — tell the user honestly.
+      snap = { ...snap, status: 'unavailable', error: 'expired_token' };
+      emit();
+      return snapshot();
+    }
+    const res = await fetchUsage({ token: cred.token, ua: userAgent(env), fetchImpl });
+    if (res.ok) {
+      snap = {
+        status: 'live',
+        plan: parseUsage(res.body),
+        context: snap.context, // context is updated separately by setContext()
+        fetchedAt: now(),
+        error: null,
+      };
+      emit();
+      return snapshot();
+    }
+    // Degrade. On 429 set a backoff. Keep last-good plan data if we had any.
+    if (res.status === 429) backoffUntil = now() + BACKOFF_MS;
+    const hadData = snap.plan != null;
+    snap = {
+      ...snap,
+      status: hadData ? 'stale' : 'unavailable',
+      error: res.error || `http_${res.status}`,
+    };
+    emit();
+    return snapshot();
+  }
+
+  // The local context gauge — fed by the server when an assistant turn reports usage
+  // (see index.mjs wiring). No network. Pushes an update so the gauge moves per-turn.
+  function setContext(usage, model) {
+    snap = { ...snap, context: computeContext(usage || {}, model || '') };
+    emit();
+    return snap.context;
+  }
+
+  function snapshot() {
+    return {
+      status: snap.status,
+      plan: snap.plan,
+      context: snap.context,
+      fetchedAt: snap.fetchedAt,
+      error: snap.error,
+      // The ack travels with the snapshot so the UI knows whether to show the
+      // one-time disclosure before first activation.
+      disclosed: isDisclosed(),
+    };
+  }
+
+  // --- disclosure ack ---
+  function isDisclosed() {
+    try {
+      const v = JSON.parse(fs.readFileSync(ackFile, 'utf8'));
+      return v?.acknowledged === true;
+    } catch {
+      return false;
+    }
+  }
+  function acknowledge() {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      const tmp = `${ackFile}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify({ acknowledged: true, ts: now() }, null, 2));
+      fs.renameSync(tmp, ackFile);
+    } catch {
+      /* read-only fs — degrade to not-persisted (will re-ask, harmless) */
+    }
+    return true;
+  }
+
+  // --- timer ---
+  function start() {
+    if (timer) return; // idempotent
+    // Lazy first fetch (don't block startup); then the steady cadence.
+    refresh();
+    timer = setInterval(refresh, pollMs);
+    if (timer.unref) timer.unref(); // never keep the process alive for a gauge
+  }
+  function stop() {
+    if (timer) { clearInterval(timer); timer = null; }
+  }
+
+  return {
+    dir, ackFile,
+    refresh, snapshot, setContext,
+    isDisclosed, acknowledge,
+    start, stop,
+  };
+}