@zuzuucodes/cli 1.5.0 → 1.6.0

package/bin/zuzuu.mjs

@@ -21,11 +21,12 @@ import { doctor } from '../zuzuu/commands/doctor.mjs';
 import { enable, disable } from '../zuzuu/commands/enable.mjs';
 import { runHook } from '../zuzuu/commands/hook.mjs';
 import { remember, recall, knowledge } from '../zuzuu/commands/knowledge.mjs';
-import { review, proposals } from '../zuzuu/commands/review.mjs';
+import { review } from '../zuzuu/commands/review.mjs';
+import { proposals } from '../zuzuu/commands/proposals.mjs';
 import { distill } from '../zuzuu/commands/distill.mjs';
 import { digest } from '../zuzuu/commands/digest.mjs';
 import { act } from '../zuzuu/commands/act.mjs';
-import { migrate } from '../zuzuu/commands/migrate.mjs';
+import { migrate } from '../zuzuu/commands/migrations/index.mjs';
 import { generation } from '../zuzuu/commands/generation.mjs';
 import { evalCmd } from '../zuzuu/commands/eval.mjs';
 import { code } from '../zuzuu/commands/code.mjs';
@@ -33,6 +34,7 @@ import { web } from '../zuzuu/commands/web.mjs';
 import { explain } from '../zuzuu/commands/explain.mjs';
 import { inbox } from '../zuzuu/commands/inbox.mjs';
 import { session } from '../zuzuu/commands/session.mjs';
+import { sessions } from '../zuzuu/commands/sessions.mjs';
 import { faculty } from '../zuzuu/commands/faculty.mjs';
 
 function parseArgs(argv) {
@@ -79,6 +81,9 @@ usage: zuzuu <command> [options]
                             list a faculty's envelope items (one doc · one line per item)
   faculty schema <f> [--json]
                             print a faculty's payload schema (JSON-Schema subset)
+  faculty manifest <f> [--json]
+                            print a faculty's module manifest (faculty.json)
+  faculty overview [--json] every faculty in one shot: ui + counts + top items + pending
   digest [--json] [--budget N]
                             print the session-start grounding brief
   act [list|show <slug>|new <slug>|schema <slug>]
@@ -99,6 +104,9 @@ usage: zuzuu <command> [options]
   disable                   remove the background hooks
   session [status|merge|continue|discard]
                             the invisible session branch (one per agent session)
+  sessions [--json]         recorded sessions with lifecycle state labels
+  session inspect <id> [--json]
+                            one session: trace summary + per-faculty mined signals
   eval [--faculty f]        rank pending proposals by eval score, highest first
   migrate [--home|--items]  one-time migrators: proposal schema · --home moves agent/ → .zuzuu/
                             · --items rewrites legacy faculty shapes → the envelope standard
@@ -123,7 +131,7 @@ switch (cmd) {
   case 'knowledge': await knowledge(args); break;
   case 'digest': digest(args); break;
   case 'act': act(args); break;
-  case 'distill': distill(args); break;
+  case 'distill': await distill(args); break;
   case 'inbox': inbox(args); break;
   case 'review': await review(args); break;
   case 'proposals': proposals(args); break;
@@ -134,6 +142,7 @@ switch (cmd) {
   case 'disable': disable(args); break;
   case 'hook': runHook(args._[0], { host: args.host, session: args.session }); break;
   case 'session': session(args); break;
+  case 'sessions': sessions(args); break;
   case 'faculty': faculty(args); break;
   case 'eval': evalCmd(args); break;
   case 'migrate': migrate(args); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuzuucodes/cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/web-app/dist/auth.js

@@ -0,0 +1,91 @@
+// The daemon's auth + request-origin gates, extracted from server.ts:
+// Host-header allowlist (DNS rebinding), Origin allowlist (cross-site WS
+// hijacking / CSRF), and token-in-URL → HttpOnly cookie auth. One AuthGate
+// instance guards both the Hono HTTP app and the WS upgrade path.
+import crypto from "node:crypto";
+import { getCookie, setCookie } from "hono/cookie";
+const AUTH_COOKIE = "webcode_auth";
+const COOKIE_MAX_AGE = 30 * 24 * 3600;
+export class AuthGate {
+    authSessions = new Set();
+    allowedHosts;
+    allowedOrigins;
+    token;
+    constructor(cfg) {
+        this.token = cfg.token;
+        const hostNames = ["127.0.0.1", "localhost", "[::1]"];
+        this.allowedHosts = new Set(hostNames.flatMap((h) => [h, `${h}:${cfg.port}`]));
+        this.allowedOrigins = new Set([
+            ...hostNames.map((h) => `http://${h}:${cfg.port}`),
+            ...(cfg.extraOrigins ?? []),
+        ]);
+        // hosted: also accept the public hostname (Fly's edge sets Host to it);
+        // Host/Origin defense stays on, just widened to the one public origin.
+        if (cfg.publicHost) {
+            this.allowedHosts.add(cfg.publicHost.toLowerCase());
+            this.allowedOrigins.add(`https://${cfg.publicHost}`);
+            this.allowedOrigins.add(`http://${cfg.publicHost}`);
+        }
+    }
+    /** Host allowlist defeats DNS rebinding: rebinding changes DNS, not the Host header. */
+    hostAllowed(host) {
+        return !!host && this.allowedHosts.has(host.toLowerCase());
+    }
+    /** Origin allowlist defeats cross-site WS hijacking / CSRF from arbitrary websites. */
+    originAllowed(origin) {
+        return origin === undefined || this.allowedOrigins.has(origin);
+    }
+    /** WS upgrade path: is the request's cookie an authenticated session? */
+    cookieAuthed(cookieHeader) {
+        if (!cookieHeader)
+            return false;
+        const match = /(?:^|;\s*)webcode_auth=([^;]+)/.exec(cookieHeader);
+        return !!match && this.authSessions.has(match[1]);
+    }
+    /** App-wide gate: Host/Origin allowlists + the ?token= → cookie exchange. */
+    gate() {
+        return async (c, next) => {
+            if (!this.hostAllowed(c.req.header("host"))) {
+                return c.text("forbidden host", 403);
+            }
+            if (!this.originAllowed(c.req.header("origin"))) {
+                return c.text("forbidden origin", 403);
+            }
+            // Token exchange: any page request carrying ?token= gets a cookie.
+            const token = c.req.query("token");
+            if (token && !c.req.path.startsWith("/api/")) {
+                if (!timingSafeEqualStr(token, this.token))
+                    return c.text("invalid token", 403);
+                const secret = crypto.randomBytes(24).toString("base64url");
+                this.authSessions.add(secret);
+                setCookie(c, AUTH_COOKIE, secret, {
+                    httpOnly: true,
+                    sameSite: "Strict",
+                    path: "/",
+                    maxAge: COOKIE_MAX_AGE,
+                });
+                const url = new URL(c.req.url);
+                url.searchParams.delete("token");
+                // /auth?token=… exists so the Vite dev server can proxy the
+                // exchange; land on the app root afterwards either way.
+                const dest = url.pathname === "/auth" ? "/" : url.pathname + url.search;
+                return c.redirect(dest);
+            }
+            await next();
+        };
+    }
+    /** /api/* gate: only cookie-authenticated sessions pass. */
+    requireAuth() {
+        return async (c, next) => {
+            if (!this.authSessions.has(getCookie(c, AUTH_COOKIE) ?? "")) {
+                return c.json({ error: "unauthorized" }, 401);
+            }
+            await next();
+        };
+    }
+}
+function timingSafeEqualStr(a, b) {
+    const ba = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return ba.length === bb.length && crypto.timingSafeEqual(ba, bb);
+}

package/web-app/dist/server.js

@@ -1,17 +1,17 @@
-import crypto from "node:crypto";
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { Hono } from "hono";
-import { getCookie, setCookie } from "hono/cookie";
 import { serve } from "@hono/node-server";
 import { WebSocketServer } from "ws";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { SessionManager } from "./sessions.js";
+import { AuthGate } from "./auth.js";
 import { createFsApi } from "./fs-api.js";
-import { createZuzuuApi, runZuzuuMut } from "./zuzuu-api.js";
+import { createZuzuuApi } from "./zuzuu-routes.js";
+import { runZuzuuMut } from "./zuzuu-cli.js";
 import { search } from "./search.js";
 import { listFiles } from "./file-list.js";
 import { listWorkflows, saveWorkflow } from "./workflows.js";
@@ -23,8 +23,6 @@ const execFileAsync = promisify(execFile);
 import { handleTermSocket } from "./ws-term.js";
 import { handleFsSocket } from "./ws-fs.js";
 import { PathError, resolveSafe, safeJoin } from "./safe-path.js";
-const AUTH_COOKIE = "webcode_auth";
-const COOKIE_MAX_AGE = 30 * 24 * 3600;
 /** Host CLIs an agent/command session may run. Argv-spawned, never a shell. */
 const DEFAULT_COMMAND_ALLOWLIST = ["claude", "gemini", "codex", "pi", "opencode", "zuzuu"];
 const STATIC_MIME = {
@@ -45,9 +43,7 @@ export class WebcodeServer {
     /** mutable workspace root — switchable at runtime via switchTo() */
     root;
     startedAt = Date.now();
-    authSessions = new Set();
-    allowedHosts;
-    allowedOrigins;
+    auth;
     commandAllowlist;
     server = null;
     constructor(cfg) {
@@ -55,19 +51,12 @@ export class WebcodeServer {
         this.root = cfg.root;
         this.commandAllowlist = new Set(cfg.commandAllowlist ?? DEFAULT_COMMAND_ALLOWLIST);
         this.sessions = new SessionManager(cfg.root);
-        const hostNames = ["127.0.0.1", "localhost", "[::1]"];
-        this.allowedHosts = new Set(hostNames.flatMap((h) => [h, `${h}:${cfg.port}`]));
-        this.allowedOrigins = new Set([
-            ...hostNames.map((h) => `http://${h}:${cfg.port}`),
-            ...(cfg.extraOrigins ?? []),
-        ]);
-        // hosted: also accept the public hostname (Fly's edge sets Host to it);
-        // Host/Origin defense stays on, just widened to the one public origin.
-        if (cfg.publicHost) {
-            this.allowedHosts.add(cfg.publicHost.toLowerCase());
-            this.allowedOrigins.add(`https://${cfg.publicHost}`);
-            this.allowedOrigins.add(`http://${cfg.publicHost}`);
-        }
+        this.auth = new AuthGate({
+            port: cfg.port,
+            token: cfg.token,
+            ...(cfg.extraOrigins !== undefined ? { extraOrigins: cfg.extraOrigins } : {}),
+            ...(cfg.publicHost !== undefined ? { publicHost: cfg.publicHost } : {}),
+        });
         this.app = this.buildApp();
     }
     /**
@@ -101,60 +90,13 @@ export class WebcodeServer {
             return { cliAbsent: true };
         return { ok: false, ...(r.stderr !== undefined ? { stderr: r.stderr } : {}), ...(r.data !== undefined ? { refusal: r.data } : {}) };
     }
-    // ── security gates ─────────────────────────────────────────────────
-    /** Host allowlist defeats DNS rebinding: rebinding changes DNS, not the Host header. */
-    hostAllowed(host) {
-        return !!host && this.allowedHosts.has(host.toLowerCase());
-    }
-    /** Origin allowlist defeats cross-site WS hijacking / CSRF from arbitrary websites. */
-    originAllowed(origin) {
-        return origin === undefined || this.allowedOrigins.has(origin);
-    }
-    cookieAuthed(cookieHeader) {
-        if (!cookieHeader)
-            return false;
-        const match = /(?:^|;\s*)webcode_auth=([^;]+)/.exec(cookieHeader);
-        return !!match && this.authSessions.has(match[1]);
-    }
     // ── HTTP app ───────────────────────────────────────────────────────
     buildApp() {
         const { cfg } = this;
         const app = new Hono();
-        app.use("*", async (c, next) => {
-            if (!this.hostAllowed(c.req.header("host"))) {
-                return c.text("forbidden host", 403);
-            }
-            if (!this.originAllowed(c.req.header("origin"))) {
-                return c.text("forbidden origin", 403);
-            }
-            // Token exchange: any page request carrying ?token= gets a cookie.
-            const token = c.req.query("token");
-            if (token && !c.req.path.startsWith("/api/")) {
-                if (!timingSafeEqualStr(token, cfg.token))
-                    return c.text("invalid token", 403);
-                const secret = crypto.randomBytes(24).toString("base64url");
-                this.authSessions.add(secret);
-                setCookie(c, AUTH_COOKIE, secret, {
-                    httpOnly: true,
-                    sameSite: "Strict",
-                    path: "/",
-                    maxAge: COOKIE_MAX_AGE,
-                });
-                const url = new URL(c.req.url);
-                url.searchParams.delete("token");
-                // /auth?token=… exists so the Vite dev server can proxy the
-                // exchange; land on the app root afterwards either way.
-                const dest = url.pathname === "/auth" ? "/" : url.pathname + url.search;
-                return c.redirect(dest);
-            }
-            await next();
-        });
-        app.use("/api/*", async (c, next) => {
-            if (!this.authSessions.has(getCookie(c, AUTH_COOKIE) ?? "")) {
-                return c.json({ error: "unauthorized" }, 401);
-            }
-            await next();
-        });
+        // security gates live in auth.ts: Host/Origin allowlists + token→cookie
+        app.use("*", this.auth.gate());
+        app.use("/api/*", this.auth.requireAuth());
         app.get("/api/workspace", (c) => {
             const body = {
                 root: this.root,
@@ -434,11 +376,11 @@ export class WebcodeServer {
                 socket.write(`HTTP/1.1 ${status} ${msg}\r\nConnection: close\r\n\r\n`);
                 socket.destroy();
             };
-            if (!this.hostAllowed(req.headers.host))
+            if (!this.auth.hostAllowed(req.headers.host))
                 return reject(403, "Forbidden");
-            if (!this.originAllowed(req.headers.origin))
+            if (!this.auth.originAllowed(req.headers.origin))
                 return reject(403, "Forbidden");
-            if (!this.cookieAuthed(req.headers.cookie))
+            if (!this.auth.cookieAuthed(req.headers.cookie))
                 return reject(401, "Unauthorized");
             const url = new URL(req.url ?? "/", "http://localhost");
             const termMatch = /^\/ws\/term\/([0-9a-f]+)$/.exec(url.pathname);
@@ -462,8 +404,3 @@ export class WebcodeServer {
         this.server?.close();
     }
 }
-function timingSafeEqualStr(a, b) {
-    const ba = Buffer.from(a);
-    const bb = Buffer.from(b);
-    return ba.length === bb.length && crypto.timingSafeEqual(ba, bb);
-}

package/web-app/dist/zuzuu-cli.js

@@ -0,0 +1,124 @@
+// The zuzuu CLI spawn layer — the ONLY place the daemon shells out to the
+// `zuzuu` binary. Two flavours:
+//   runZuzuu    — reads: any failure (absent, non-zero, unparseable) → null;
+//                 callers degrade to file-read fallbacks.
+//   runZuzuuMut — mutations + CLI-only reads: failures are distinguished
+//                 (binary absent vs command failed + stderr tail) so routes
+//                 can answer 503 vs 502.
+// Always argv arrays (never a shell), time-boxed, cwd-scoped to the workspace.
+import { spawn, spawnSync } from "node:child_process";
+/** Spawn `zuzuu <args> --json` in `root`. Returns parsed JSON, or null on any
+ *  failure (binary absent, non-zero exit, unparseable). Read-only + time-boxed. */
+export function runZuzuu(root, args, opts = {}) {
+    const binary = opts.binary ?? "zuzuu";
+    const timeoutMs = opts.timeoutMs ?? 5000;
+    return new Promise((resolve) => {
+        let out = "";
+        let done = false;
+        const finish = (v) => { if (!done) {
+            done = true;
+            resolve(v);
+        } };
+        let child;
+        try {
+            child = spawn(binary, [...args, "--json"], { cwd: root, stdio: ["ignore", "pipe", "ignore"] });
+        }
+        catch {
+            finish(null);
+            return;
+        }
+        const timer = setTimeout(() => { try {
+            child.kill();
+        }
+        catch { /* noop */ } finish(null); }, timeoutMs);
+        child.stdout?.on("data", (b) => { out += b.toString(); });
+        child.on("error", () => { clearTimeout(timer); finish(null); });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code !== 0)
+                return finish(null);
+            try {
+                finish(JSON.parse(out));
+            }
+            catch {
+                finish(null);
+            }
+        });
+    });
+}
+const STDERR_TAIL = 2048;
+/** Spawn `zuzuu <args> --json` where the caller needs to distinguish failures
+ *  (mutations, and reads with no file fallback). Unlike runZuzuu: binary
+ *  absent vs command failed (with a stderr tail) are separate results, so
+ *  routes can answer 503 vs 502. Stdout must parse as JSON on success. */
+export function runZuzuuMut(root, args, opts = {}) {
+    const binary = opts.binary ?? "zuzuu";
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    return new Promise((resolve) => {
+        let out = "";
+        let err = "";
+        let done = false;
+        const finish = (v) => { if (!done) {
+            done = true;
+            resolve(v);
+        } };
+        let child;
+        try {
+            child = spawn(binary, [...args, "--json"], { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch {
+            finish({ ok: false, code: "absent" });
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                child.kill();
+            }
+            catch { /* noop */ }
+            finish({ ok: false, code: "failed", stderr: "zuzuu timed out" });
+        }, timeoutMs);
+        child.stdout?.on("data", (b) => { out += b.toString(); });
+        child.stderr?.on("data", (b) => {
+            err += b.toString();
+            if (err.length > STDERR_TAIL)
+                err = err.slice(-STDERR_TAIL);
+        });
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            if (e.code === "ENOENT")
+                finish({ ok: false, code: "absent" });
+            else
+                finish({ ok: false, code: "failed", stderr: e.message });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                // zuzuu prints structured JSON even on refusals (exit 1, e.g.
+                // empty-squash-with-checkpoints) — keep it so the UI can act on reason.
+                try {
+                    const parsed = JSON.parse(out);
+                    return finish({ ok: false, code: "failed", stderr: err.slice(-STDERR_TAIL), data: parsed });
+                }
+                catch {
+                    return finish({ ok: false, code: "failed", stderr: err.slice(-STDERR_TAIL) });
+                }
+            }
+            try {
+                finish({ ok: true, data: JSON.parse(out) });
+            }
+            catch {
+                finish({ ok: false, code: "failed", stderr: "unparseable JSON from zuzuu" });
+            }
+        });
+    });
+}
+/** Best-effort: is the zuzuu binary runnable? */
+export function binAvailable(binary) {
+    try {
+        const r = spawnSync(binary, ["version"], { stdio: "ignore", timeout: 3000 });
+        return !r.error && r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}

package/web-app/dist/{zuzuu-api.js → zuzuu-routes.js}

@@ -1,133 +1,20 @@
 // /api/zuzuu/* — observe + act routes over a project's zuzuu `.zuzuu/` home.
 // Reads: raw data (proposals, generations, sessions, digest) comes from disk;
 // computed views (status, inbox, eval, generation diff) shell out to
-// `zuzuu <cmd> --json` and fall back to file-reads when the binary is absent.
+// `zuzuu <cmd> --json` (the spawn layer lives in zuzuu-cli.ts) and fall back
+// to file-reads when the binary is absent.
 // Writes: mutations (approve/reject, mint, rollback) are CLI-ONLY — the daemon
 // never reimplements faculty writes; no CLI → 503. Mirrors fs-api.ts.
 import fsp from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { spawn, spawnSync } from "node:child_process";
 import path from "node:path";
 import { Hono } from "hono";
 import { PathError, resolveSafe } from "./safe-path.js";
+import { binAvailable, runZuzuu, runZuzuuMut } from "./zuzuu-cli.js";
 const FACULTIES = ["knowledge", "memory", "actions", "instructions", "guardrails"];
 /** Ids/slugs/generation-ids that may ride into a zuzuu argv. Validated BEFORE any spawn. */
 const SAFE_ID = /^[a-z0-9][a-z0-9._-]{0,127}$/i;
 const MAX_REASON_LEN = 500;
-/** Spawn `zuzuu <args> --json` in `root`. Returns parsed JSON, or null on any
- *  failure (binary absent, non-zero exit, unparseable). Read-only + time-boxed. */
-export function runZuzuu(root, args, opts = {}) {
-    const binary = opts.binary ?? "zuzuu";
-    const timeoutMs = opts.timeoutMs ?? 5000;
-    return new Promise((resolve) => {
-        let out = "";
-        let done = false;
-        const finish = (v) => { if (!done) {
-            done = true;
-            resolve(v);
-        } };
-        let child;
-        try {
-            child = spawn(binary, [...args, "--json"], { cwd: root, stdio: ["ignore", "pipe", "ignore"] });
-        }
-        catch {
-            finish(null);
-            return;
-        }
-        const timer = setTimeout(() => { try {
-            child.kill();
-        }
-        catch { /* noop */ } finish(null); }, timeoutMs);
-        child.stdout?.on("data", (b) => { out += b.toString(); });
-        child.on("error", () => { clearTimeout(timer); finish(null); });
-        child.on("close", (code) => {
-            clearTimeout(timer);
-            if (code !== 0)
-                return finish(null);
-            try {
-                finish(JSON.parse(out));
-            }
-            catch {
-                finish(null);
-            }
-        });
-    });
-}
-const STDERR_TAIL = 2048;
-/** Spawn `zuzuu <args> --json` for a MUTATION. Unlike runZuzuu, failures are
- *  distinguished: binary absent vs command failed (with a stderr tail), so
- *  routes can answer 503 vs 502. Stdout must parse as JSON on success. */
-export function runZuzuuMut(root, args, opts = {}) {
-    const binary = opts.binary ?? "zuzuu";
-    const timeoutMs = opts.timeoutMs ?? 10_000;
-    return new Promise((resolve) => {
-        let out = "";
-        let err = "";
-        let done = false;
-        const finish = (v) => { if (!done) {
-            done = true;
-            resolve(v);
-        } };
-        let child;
-        try {
-            child = spawn(binary, [...args, "--json"], { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
-        }
-        catch {
-            finish({ ok: false, code: "absent" });
-            return;
-        }
-        const timer = setTimeout(() => {
-            try {
-                child.kill();
-            }
-            catch { /* noop */ }
-            finish({ ok: false, code: "failed", stderr: "zuzuu timed out" });
-        }, timeoutMs);
-        child.stdout?.on("data", (b) => { out += b.toString(); });
-        child.stderr?.on("data", (b) => {
-            err += b.toString();
-            if (err.length > STDERR_TAIL)
-                err = err.slice(-STDERR_TAIL);
-        });
-        child.on("error", (e) => {
-            clearTimeout(timer);
-            if (e.code === "ENOENT")
-                finish({ ok: false, code: "absent" });
-            else
-                finish({ ok: false, code: "failed", stderr: e.message });
-        });
-        child.on("close", (code) => {
-            clearTimeout(timer);
-            if (code !== 0) {
-                // zuzuu prints structured JSON even on refusals (exit 1, e.g.
-                // empty-squash-with-checkpoints) — keep it so the UI can act on reason.
-                try {
-                    const parsed = JSON.parse(out);
-                    return finish({ ok: false, code: "failed", stderr: err.slice(-STDERR_TAIL), data: parsed });
-                }
-                catch {
-                    return finish({ ok: false, code: "failed", stderr: err.slice(-STDERR_TAIL) });
-                }
-            }
-            try {
-                finish({ ok: true, data: JSON.parse(out) });
-            }
-            catch {
-                finish({ ok: false, code: "failed", stderr: "unparseable JSON from zuzuu" });
-            }
-        });
-    });
-}
-/** Best-effort: is the zuzuu binary runnable? */
-function binAvailable(binary) {
-    try {
-        const r = spawnSync(binary, ["version"], { stdio: "ignore", timeout: 3000 });
-        return !r.error && r.status === 0;
-    }
-    catch {
-        return false;
-    }
-}
 // ── Faculty Standard envelope listing ────────────────────────────────────
 // The CLI is the parser of record (`zuzuu faculty items <f> --json` returns
 // the full envelopes incl. payload/body). When it's absent we degrade to a
@@ -278,6 +165,28 @@ export function createZuzuuApi(getRoot, opts = {}) {
         }));
         return c.json({ faculties });
     });
+    // The batched faculty surface: ONE `zuzuu faculty overview --json` spawn
+    // covers all faculties (manifest ui descriptors + counts + top titles +
+    // pending) — replaces the 5-spawn-per-cycle /faculties pattern for the
+    // panel root. CLI absent → peek fallback (counts survive, ui descriptors
+    // degrade to the web kit's built-in metadata).
+    app.get("/overview", async (c) => {
+        const viaCli = await runZuzuu(root, ["faculty", "overview"], { binary: opts.binary });
+        if (viaCli && Array.isArray(viaCli.faculties))
+            return c.json(viaCli);
+        const agent = await agentDir();
+        const faculties = await Promise.all(FACULTIES.map(async (id) => {
+            const [items, proposals] = await Promise.all([peekFacultyItems(agent, id), proposalsOf(agent, id)]);
+            return {
+                id,
+                title: id.charAt(0).toUpperCase() + id.slice(1),
+                counts: { items: items.length, pending: proposals.length, errors: 0 },
+                top: items.slice(0, 3).map((it) => String(it.title ?? it.id)),
+                declarative: false,
+            };
+        }));
+        return c.json({ faculties, degraded: true });
+    });
     app.get("/faculty/:key", async (c) => {
         const key = c.req.param("key");
         if (!FACULTIES.includes(key))
@@ -320,7 +229,13 @@ export function createZuzuuApi(getRoot, opts = {}) {
             generations: gens.map((g) => ({ id: String(g.id), mintedAt: g.mintedAt ?? null, mintedFrom: g.mintedFrom ?? [] })),
         });
     });
+    // Sessions list: CLI-first (`zuzuu sessions --json` — state-labelled:
+    // active|completed|abandoned|crashed|captured); falls back to the raw
+    // sessions.json index (no state labels) when the CLI is absent.
     app.get("/sessions", async (c) => {
+        const viaCli = await runZuzuu(root, ["sessions"], { binary: opts.binary });
+        if (viaCli && Array.isArray(viaCli.sessions))
+            return c.json(viaCli);
         const agent = await agentDir();
         try {
             const idx = JSON.parse(await fsp.readFile(path.join(agent, "sessions.json"), "utf8"));
@@ -330,6 +245,21 @@ export function createZuzuuApi(getRoot, opts = {}) {
             return c.json({ sessions: [] });
         }
     });
+    // One session's observability document (`zuzuu session inspect <id> --json`:
+    // trace summary + per-faculty mined signals + warnings). CLI-only — the
+    // daemon never re-mines transcripts; absent → 503, failed → 502.
+    app.get("/session-inspect/:id", async (c) => {
+        const id = c.req.param("id");
+        if (!SAFE_ID.test(id))
+            return c.json({ error: "bad id" }, 400);
+        const r = await runZuzuuMut(root, ["session", "inspect", id], { binary: opts.binary });
+        if (!r.ok) {
+            return r.code === "absent"
+                ? c.json({ error: "zuzuu CLI required" }, 503)
+                : c.json({ error: "zuzuu command failed", stderr: r.stderr ?? "", data: r.data ?? null }, 502);
+        }
+        return c.json(r.data);
+    });
     app.get("/digest", async (c) => {
         const agent = await agentDir();
         try {