feat: ak admin — maintainer-only local telemetry admin (ADR-0007)

MAINTAINER.md

@@ -24,7 +24,7 @@ release this kit. User-facing docs live in [README.md](README.md); this file is
 
 ### CLI shape (`bin/agentic-kit.mjs`)
 
-- **Porcelain** (daily): `setup`, `status`, `sync`, `dashboard`, `uninstall`. Bare `ak` → `status --hint`. (`dashboard` is also reachable as `ak x dashboard`.)
+- **Porcelain** (daily): `setup`, `status`, `sync`, `dashboard`, `admin`, `dual`, `uninstall`. Bare `ak` → `status --hint`. (`dashboard` and `admin` are also reachable as `ak x dashboard` / `ak x admin`.)
 - **Plumbing** (power users): `ak x daemon-gc | mcp | reference | verify | improvement-eval`.
 - Each command module exports `options` (a `parseArgs` config) and `run({ flags, positionals, pkgRoot })`.
 - A best-effort drift nudge runs after non-`sync`, non-`--json` commands.
@@ -39,7 +39,7 @@ src/
   commands/              # porcelain verbs
     setup.mjs  status.mjs  sync.mjs  dual.mjs  uninstall.mjs
     x/                   # plumbing verbs
-      daemon-gc.mjs  dashboard.mjs  harvest.mjs  mcp.mjs  provider.mjs  reference.mjs  verify.mjs
+      admin.mjs  daemon-gc.mjs  dashboard.mjs  harvest.mjs  mcp.mjs  provider.mjs  reference.mjs  verify.mjs
   lib/                   # the engine — each file is one concern
     heal.mjs             # the mutations sync/setup apply (idempotent, {ok,detail})
     natives.mjs          # better-sqlite3 / agentdb native detection
@@ -54,6 +54,11 @@ src/
     agentdb.mjs          # agentdb CLI coherence (harvest write path)
     health-history.mjs   # regression ring appended by sync, read by status
     dashboard-server.mjs # read-only localhost dashboard (shells `ak status --json`)
+    admin-server.mjs     # maintainer admin: loopback server, per-session token auth, page assembly (ADR-0007)
+    admin-collect.mjs    # admin's server-side GitHub/npm fan-out → typed payload (injectable fetchers)
+    admin-model.mjs      # PURE admin number model — imports nothing; embedded in the page AND node-tested
+    admin-view.mjs       # admin browser controller (embedded into the page; not node-imported)
+    browser.mjs          # openInBrowser — shared by dashboard + admin
     npx.mjs              # stale npx-cache detection/prune
     mcp.mjs  settings.mjs  config.mjs  paths.mjs  statusline.mjs
     rvf.mjs  daemons.mjs  exec.mjs  output.mjs

README.md

@@ -70,6 +70,7 @@ What the verbs cover:
 | **status** | Per-subsystem ✓/⚠/✗ (versions, the kit's own version, **ruvnet-brain** (present + release drift, or "not installed"), natives, security, learning, aqe/RVF, **agentdb** (CLI present + coherent with ruflo's bundled version, or a store-skew warning), MCP, **hosts** (claude/codex — version + install method + **auth mode** (subscription $0 vs metered api-key), with the **primary** host marked and a *fail* when the primary host is absent), **providers** (host wiring + aqe fallback chain, or "drifted"/claude-only default), **routing** (per-activity Claude/Codex host+model policy, when dual-host — with drift vs the on-disk `agentOverrides`), daemons, CLAUDE.md blocks, statusline), each drift row naming what `sync` would do about it — plus a **health-history** line that flags regressions since the last sync (learning shrank, native slots dropped, drift/security backslid). |
 | **sync** | The one convergence verb: upgrades first when a new release exists, then re-heals everything an upgrade wipes, then re-checks and reports. Included in that heal: it **installs any enabled frontier host** (claude/codex) that's entirely absent — never touching an external (mise/brew/native) install — and **re-applies provider wiring** (the `ENABLE_*` host env, the aqe fallback chain, and ruflo API providers) whenever it has drifted — and, on a dual-host project, **seeds/heals the per-activity routing policy** (materializing it into agentic-qe's `agentOverrides`, e.g. after an aqe upgrade first makes it eligible). It also **installs/repins the standalone `agentdb` CLI** to ruflo's bundled version (keeping the shared cognitive store coherent) and appends a **health-history snapshot** so `status` can flag regressions across syncs. It also **re-runs the RuvNet Brain installer** to pull the latest release when the on-disk KB has drifted (or installs it if absent, when enabled). It also **self-updates the kit**: when a newer `@pacphi/agentic-kit` exists it installs it as the *last* step (the new code applies from the next `ak` run, never mid-sync). Prerelease installs (`4.0.0-alpha.*`) track the `next` npm dist-tag as well as `latest`, so alphas see their successors; stable installs only ever follow `latest`. `--no-upgrade` skips the self-update along with the package upgrades. |
 | **dashboard** | Opens a read-only local web dashboard (`127.0.0.1:7431`, localhost-only, never detaches) that renders the same subsystem view as `ak status` in an Apple-style five-tab layout — **Overview · Hosts & Routing · Providers · Runtime · Intelligence** — with count badges on any tab holding a failing/warning subsystem. Problems never hide behind a tab: Overview aggregates every attention card, a quiet update notice, and a jump-to status map of all subsystems; Providers shows the **models in play** (distinct host+model pairs from your routing policy); Hosts & Routing carries the **per-activity routing matrix** (vendor-coded Claude/Codex host + model per activity) when dual-host routing is configured; Intelligence keeps the learning-over-time strip. Fully self-contained and offline (no external fetches, nothing leaves your machine). **Auto-opens your browser** (`--no-open` to just print the URL for headless/SSH); `--port N` to change the port; tabs deep-link (`#providers`) and persist. Stop with Ctrl-C. (Also available as `ak x dashboard`.) |
+| **admin** | Opens the **maintainer admin** (`127.0.0.1:7432`, localhost-only, foreground) — the project-telemetry sibling of `dashboard`: unique repo visitors and cloners (GitHub traffic API, needs a push-access token via `GITHUB_TOKEN`/`GH_TOKEN`/`gh auth token` — panels degrade honestly without one), npm download momentum (last 7d vs prior 7d, sparklines), release pulls, a **"since you last looked"** delta strip over a local baseline, open issues/PRs from others (oldest first), and external humans ranked by recency (bots excluded). Access is gated by a **per-session token** carried in the URL fragment and sent header-only; the page makes **zero external fetches** (the server proxies GitHub/npm; your credential never reaches the page or the payload — ADR-0007). Where `dashboard` is offline-first, `admin` does deliberate GitHub/npm egress — that contract split is why they're siblings, not tabs. `--port N`, `--no-open`; Ctrl-C stops. (Also available as `ak x admin`.) |
 | **dual** | Runs a **Claude + Codex collaboration swarm** using your per-activity routing policy: `ak dual run <template> "<task>"` materializes a dual-run config (each pipeline step assigned to the host + model your policy chose) and drives it via `claude-flow-codex`. Templates: `feature`, `security`, `refactor`, `packaging`, `release`. `--dry-run` prints the plan + config without running; `--route 'activity:host[:model]'` overrides one step for that run; `--escalate` retries once up the cross-vendor ladder on failure. Requires dual-host enabled (`ak setup --codex`, or `ak x provider pick --host claude,codex`). |
 | **uninstall** | Removes the kit's footprint (and any legacy shell-kit install); project data is never touched; `--purge` also offers to remove the global packages. |
 

bin/agentic-kit.mjs

@@ -13,11 +13,13 @@ const PORCELAIN = {
   sync: () => import('../src/commands/sync.mjs'),
   setup: () => import('../src/commands/setup.mjs'),
   dashboard: () => import('../src/commands/x/dashboard.mjs'),
+  admin: () => import('../src/commands/x/admin.mjs'),
   dual: () => import('../src/commands/dual.mjs'),
   uninstall: () => import('../src/commands/uninstall.mjs'),
 };
 
 const PLUMBING = {
+  'admin': () => import('../src/commands/x/admin.mjs'),
   'daemon-gc': () => import('../src/commands/x/daemon-gc.mjs'),
   'dashboard': () => import('../src/commands/x/dashboard.mjs'),
   'harvest': () => import('../src/commands/x/harvest.mjs'),
@@ -35,6 +37,7 @@ Usage (ak = alias of agentic-kit):
   ak status          read-only dashboard: what's true, what's drifted  [--json] [--deep]
   ak sync            converge to good: upgrade + heal + verify          [--dry-run] [--no-upgrade]
   ak dashboard       open the local web dashboard (localhost; auto-opens browser)  [--port N] [--no-open]
+  ak admin           maintainer-only telemetry admin (localhost; GitHub/npm egress)  [--port N] [--no-open]
   ak dual            run a Claude+Codex collaboration swarm (dual-host)  [run <template> "task"] [--dry-run]
   ak uninstall       leave cleanly                                      [--this-project] [--purge]
 
@@ -51,6 +54,7 @@ More:
 const HELP_ALL = `${HELP}
 
 Plumbing (power users) — each takes --help:
+  ak x admin [--port N]        maintainer-only telemetry admin (localhost; GitHub/npm egress)
   ak x daemon-gc [--kill]      list/stop stale ruflo daemons
   ak x dashboard [--port N]    read-only local health dashboard (localhost only)
   ak x harvest [--dry-run]     opt-in learning-write: replay experiences into the substrate