@tpsdev-ai/flair 0.8.3 → 0.10.0

package/dist/rem/scheduler.js

@@ -0,0 +1,240 @@
+/**
+ * REM nightly scheduler — platform-native scheduler install/uninstall.
+ *
+ * Per FLAIR-NIGHTLY-REM § 3 (`flair rem nightly enable|disable`). Renders
+ * launchd plist (macOS) or systemd timer+service (Linux) from templates,
+ * deploys a shim script to `~/.flair/bin/flair-rem-nightly`, and loads the
+ * job into the user-session scheduler.
+ *
+ * Templates use `{{KEY}}` placeholders — single-pass substitution. The full
+ * placeholder set is enumerated in `interface SchedulerSubstitutions` so
+ * adding a new key requires touching both this module and the template.
+ *
+ * No daemon code lives here — the scheduler invokes the shim, the shim
+ * invokes `flair rem nightly run-once`, the runner module does the work.
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, rmSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir, platform } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+export const SHIM_PATH_DEFAULT = resolve(homedir(), ".flair", "bin", "flair-rem-nightly");
+export const LAUNCHD_PLIST_PATH = resolve(homedir(), "Library", "LaunchAgents", "dev.flair.rem.nightly.plist");
+export const SYSTEMD_USER_DIR = resolve(homedir(), ".config", "systemd", "user");
+export const SYSTEMD_TIMER_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.timer");
+export const SYSTEMD_SERVICE_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.service");
+function detectPlatform(override) {
+    if (override)
+        return override;
+    const p = platform();
+    if (p === "darwin")
+        return "darwin";
+    if (p === "linux")
+        return "linux";
+    throw new Error(`unsupported platform for REM nightly scheduler: ${p} (only darwin and linux)`);
+}
+function defaultTemplateRoot() {
+    // Templates live alongside dist/ in the published package and alongside
+    // src/rem/ in the source tree. Walk up from this file until we find
+    // a directory containing templates/.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "..", "..", "templates"),
+        resolve(here, "..", "..", "..", "templates"),
+        resolve(here, "..", "templates"),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    throw new Error(`unable to locate templates directory (looked in: ${candidates.join(", ")})`);
+}
+export function renderTemplate(text, subs) {
+    return text.replace(/\{\{([A-Z_]+)\}\}/g, (_, key) => {
+        const value = subs[key];
+        if (value === undefined)
+            throw new Error(`unknown template placeholder: ${key}`);
+        return String(value);
+    });
+}
+export function readTemplate(rootDir, relativePath) {
+    const full = resolve(rootDir, relativePath);
+    if (!existsSync(full)) {
+        throw new Error(`template not found: ${full}`);
+    }
+    return readFileSync(full, "utf-8");
+}
+/**
+ * Validates the hour:minute schedule. Throws on invalid input rather than
+ * silently coercing — surface bad input at the install boundary.
+ */
+function validateSchedule(hour, minute) {
+    if (!Number.isInteger(hour) || hour < 0 || hour > 23) {
+        throw new Error(`hour must be an integer 0-23, got ${hour}`);
+    }
+    if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
+        throw new Error(`minute must be an integer 0-59, got ${minute}`);
+    }
+}
+function buildSubstitutions(opts, shimPath, flairBin) {
+    validateSchedule(opts.hour, opts.minute);
+    if (!/^[a-zA-Z0-9_-]+$/.test(opts.agentId)) {
+        throw new Error(`invalid agent id: ${opts.agentId}`);
+    }
+    return {
+        FLAIR_BIN: flairBin,
+        SHIM_PATH: shimPath,
+        HOME: homedir(),
+        AGENT_ID: opts.agentId,
+        FLAIR_URL: opts.flairUrl,
+        HOUR: String(opts.hour),
+        HOUR_PAD: String(opts.hour).padStart(2, "0"),
+        MINUTE: String(opts.minute),
+        MINUTE_PAD: String(opts.minute).padStart(2, "0"),
+    };
+}
+function writeFileWithDir(path, contents, mode = 0o600) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, contents, { mode });
+}
+// 30s ceiling on launchctl/systemctl invocations so a hung service manager
+// can't block the CLI indefinitely. Sherlock #415 follow-up.
+const SPAWN_TIMEOUT_MS = 30_000;
+function spawnReport(cmd) {
+    const r = spawnSync(cmd[0], cmd.slice(1), {
+        encoding: "buffer",
+        timeout: SPAWN_TIMEOUT_MS,
+    });
+    return {
+        code: r.status,
+        stdout: r.stdout?.toString("utf-8") ?? "",
+        stderr: r.stderr?.toString("utf-8") ?? "",
+    };
+}
+/**
+ * Installs the platform-native scheduler entry and the shim script.
+ *
+ * macOS: writes ~/Library/LaunchAgents/dev.flair.rem.nightly.plist + bootstraps it via launchctl.
+ * Linux: writes ~/.config/systemd/user/flair-rem-nightly.{timer,service} + enables the timer.
+ *
+ * In both cases, also deploys ~/.flair/bin/flair-rem-nightly as the shim
+ * the scheduler invokes.
+ */
+export function enableScheduler(opts) {
+    const plat = detectPlatform(opts.platformOverride);
+    const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+    const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
+    const subs = buildSubstitutions(opts, shimPath, flairBin);
+    // 1. Deploy the shim (always — both platforms invoke it).
+    const shimContents = renderTemplate(readTemplate(templateRoot, "bin/flair-rem-nightly.sh.tmpl"), subs);
+    writeFileWithDir(shimPath, shimContents, 0o700);
+    chmodSync(shimPath, 0o700);
+    // 2. Write the scheduler entry.
+    if (plat === "darwin") {
+        const plistPath = opts.launchdPlistOverride ?? LAUNCHD_PLIST_PATH;
+        const plistContents = renderTemplate(readTemplate(templateRoot, "launchd/dev.flair.rem.nightly.plist.tmpl"), subs);
+        writeFileWithDir(plistPath, plistContents, 0o600);
+        const loadCommand = ["launchctl", "bootstrap", `gui/${process.getuid?.() ?? ""}`, plistPath];
+        let loadResult;
+        if (!opts.skipLoad) {
+            // Bootout first in case a prior install left the job loaded.
+            spawnReport(["launchctl", "bootout", `gui/${process.getuid?.() ?? ""}`, plistPath]);
+            loadResult = spawnReport(loadCommand);
+        }
+        return { platform: plat, shimPath, schedulerPath: plistPath, loadCommand, loadResult };
+    }
+    // Linux: systemd user units.
+    const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
+    const servicePath = opts.systemdServiceOverride ?? SYSTEMD_SERVICE_PATH;
+    const serviceContents = renderTemplate(readTemplate(templateRoot, "systemd/flair-rem-nightly.service.tmpl"), subs);
+    const timerContents = renderTemplate(readTemplate(templateRoot, "systemd/flair-rem-nightly.timer.tmpl"), subs);
+    writeFileWithDir(servicePath, serviceContents, 0o600);
+    writeFileWithDir(timerPath, timerContents, 0o600);
+    const loadCommand = ["systemctl", "--user", "enable", "--now", "flair-rem-nightly.timer"];
+    let loadResult;
+    if (!opts.skipLoad) {
+        spawnReport(["systemctl", "--user", "daemon-reload"]);
+        loadResult = spawnReport(loadCommand);
+    }
+    return { platform: plat, shimPath, schedulerPath: timerPath, loadCommand, loadResult };
+}
+/**
+ * Removes the scheduler entry. Audit log + snapshots are preserved.
+ */
+export function disableScheduler(opts = {}) {
+    const plat = detectPlatform(opts.platformOverride);
+    const removed = [];
+    if (plat === "darwin") {
+        const plistPath = opts.launchdPlistOverride ?? LAUNCHD_PLIST_PATH;
+        const unloadCommand = ["launchctl", "bootout", `gui/${process.getuid?.() ?? ""}`, plistPath];
+        let unloadResult;
+        if (existsSync(plistPath)) {
+            if (!opts.skipUnload) {
+                unloadResult = spawnReport(unloadCommand);
+            }
+            rmSync(plistPath, { force: true });
+            removed.push(plistPath);
+        }
+        if (opts.removeShim) {
+            const shim = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+            if (existsSync(shim)) {
+                rmSync(shim, { force: true });
+                removed.push(shim);
+            }
+        }
+        return { platform: plat, removed, unloadCommand, unloadResult };
+    }
+    const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
+    const servicePath = opts.systemdServiceOverride ?? SYSTEMD_SERVICE_PATH;
+    const unloadCommand = ["systemctl", "--user", "disable", "--now", "flair-rem-nightly.timer"];
+    let unloadResult;
+    if (existsSync(timerPath) || existsSync(servicePath)) {
+        if (!opts.skipUnload) {
+            unloadResult = spawnReport(unloadCommand);
+            spawnReport(["systemctl", "--user", "daemon-reload"]);
+        }
+        if (existsSync(timerPath)) {
+            rmSync(timerPath, { force: true });
+            removed.push(timerPath);
+        }
+        if (existsSync(servicePath)) {
+            rmSync(servicePath, { force: true });
+            removed.push(servicePath);
+        }
+    }
+    if (opts.removeShim) {
+        const shim = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+        if (existsSync(shim)) {
+            rmSync(shim, { force: true });
+            removed.push(shim);
+        }
+    }
+    return { platform: plat, removed, unloadCommand, unloadResult };
+}
+/**
+ * Reports whether the scheduler is installed. Filesystem-only — does not
+ * shell out to launchctl/systemctl to query active state. The Health
+ * endpoint already does that via existence checks; same approach here.
+ */
+export function schedulerStatus(opts = {}) {
+    const plat = detectPlatform(opts.platformOverride);
+    if (plat === "darwin") {
+        return {
+            platform: plat,
+            installed: existsSync(LAUNCHD_PLIST_PATH),
+            schedulerPath: LAUNCHD_PLIST_PATH,
+            shimPath: SHIM_PATH_DEFAULT,
+            shimExists: existsSync(SHIM_PATH_DEFAULT),
+        };
+    }
+    return {
+        platform: plat,
+        installed: existsSync(SYSTEMD_TIMER_PATH) && existsSync(SYSTEMD_SERVICE_PATH),
+        schedulerPath: SYSTEMD_TIMER_PATH,
+        shimPath: SHIM_PATH_DEFAULT,
+        shimExists: existsSync(SHIM_PATH_DEFAULT),
+    };
+}

package/dist/rem/snapshot.js

@@ -0,0 +1,139 @@
+/**
+ * REM snapshot module — pre-cycle snapshot + listing + restore extraction.
+ *
+ * Per FLAIR-NIGHTLY-REM § 4 step 2 and § 9. Produces tar.gz archives at
+ * ~/.flair/snapshots/<agentId>/<ISO-timestamp>.tar.gz containing:
+ *   - memories.jsonl  — one Memory row per line
+ *   - soul.json       — Soul row (or null)
+ *   - metadata.json   — agent id, run id, flair version, counts
+ *
+ * Mirrors the `flair session snapshot` pattern (tar.gz, 600 perms, agent-
+ * rooted under ~/.flair/snapshots/). Pure filesystem — the caller fetches
+ * the data via the Harper HTTP API and passes it in.
+ *
+ * Used by:
+ *   - `flair rem snapshot list`
+ *   - `flair rem restore <date>`
+ *   - The nightly runner (slice-1 follow-on)
+ */
+import { mkdirSync, writeFileSync, statSync, chmodSync, rmSync, existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
+export const SNAPSHOT_ROOT = resolve(homedir(), ".flair", "snapshots");
+/** Validates the agent id and returns its snapshot directory. */
+export function remSnapshotDir(agent) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(agent)) {
+        throw new Error(`invalid agent id: ${agent}`);
+    }
+    return resolve(SNAPSHOT_ROOT, agent);
+}
+/**
+ * Creates a tar.gz snapshot at <root>/<agentId>/<ISO-timestamp>.tar.gz.
+ * Returns the path, byte size, and metadata embedded in the archive.
+ *
+ * Tarball perms: 0600 (owner-only).
+ */
+export async function createSnapshot(opts) {
+    const now = opts.nowOverride ?? new Date();
+    const isoFull = now.toISOString().replace(/[:.]/g, "-");
+    const root = opts.rootOverride ?? SNAPSHOT_ROOT;
+    if (!/^[a-zA-Z0-9_-]+$/.test(opts.agentId)) {
+        throw new Error(`invalid agent id: ${opts.agentId}`);
+    }
+    const dir = resolve(root, opts.agentId);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tarballName = `${isoFull}.tar.gz`;
+    const tarballPath = resolve(dir, tarballName);
+    const meta = {
+        agentId: opts.agentId,
+        runId: opts.runId ?? `rem-nightly-${isoFull}`,
+        flairVersion: opts.flairVersion,
+        createdAt: now.toISOString(),
+        memoryCount: opts.memories.length,
+        pendingCandidateCount: opts.pendingCandidateCount,
+        soulPresent: opts.soul !== null,
+    };
+    const tmpDir = resolve(dir, `.tmp-${process.pid}-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+    try {
+        const memoryLines = opts.memories.map((m) => JSON.stringify(m)).join("\n");
+        writeFileSync(resolve(tmpDir, "memories.jsonl"), memoryLines + (memoryLines.length ? "\n" : ""), { mode: 0o600 });
+        writeFileSync(resolve(tmpDir, "soul.json"), JSON.stringify(opts.soul, null, 2) + "\n", { mode: 0o600 });
+        writeFileSync(resolve(tmpDir, "metadata.json"), JSON.stringify(meta, null, 2) + "\n", { mode: 0o600 });
+        await tarCreate({ gzip: true, cwd: tmpDir, file: tarballPath, portable: true }, ["memories.jsonl", "soul.json", "metadata.json"]);
+        chmodSync(tarballPath, 0o600);
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+    return { path: tarballPath, size: statSync(tarballPath).size, meta };
+}
+/**
+ * Lists snapshots at <root>/<agent>/*.tar.gz. Returns rows sorted by mtime
+ * descending. Pass an agent filter to restrict to a single agent.
+ */
+export function listSnapshots(agentFilter, rootOverride) {
+    const root = rootOverride ?? SNAPSHOT_ROOT;
+    if (!existsSync(root))
+        return [];
+    let agents;
+    if (agentFilter) {
+        if (!/^[a-zA-Z0-9_-]+$/.test(agentFilter)) {
+            throw new Error(`invalid agent id: ${agentFilter}`);
+        }
+        agents = [agentFilter];
+    }
+    else {
+        agents = readdirSync(root).filter((d) => {
+            try {
+                return statSync(resolve(root, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    const rows = [];
+    for (const a of agents) {
+        const dir = resolve(root, a);
+        if (!existsSync(dir))
+            continue;
+        for (const f of readdirSync(dir)) {
+            if (!f.endsWith(".tar.gz"))
+                continue;
+            const p = resolve(dir, f);
+            const s = statSync(p);
+            rows.push({ agent: a, file: f, path: p, size: s.size, mtime: s.mtime.toISOString() });
+        }
+    }
+    rows.sort((a, b) => b.mtime.localeCompare(a.mtime));
+    return rows;
+}
+/**
+ * Extracts a snapshot tar.gz into a target directory. Refuses to extract
+ * over an existing directory — operator must pass a clean target.
+ *
+ * In dry-run mode, returns the tarball entry list without writing anything.
+ */
+export async function extractSnapshot(opts) {
+    if (!existsSync(opts.snapshotPath)) {
+        throw new Error(`snapshot does not exist: ${opts.snapshotPath}`);
+    }
+    const entries = [];
+    await tarList({
+        file: opts.snapshotPath,
+        onReadEntry: (e) => entries.push({ path: e.path, size: e.size ?? 0 }),
+    });
+    if (opts.dryRun) {
+        return { entries };
+    }
+    const targetDir = opts.targetDir ?? `${opts.snapshotPath}.restored`;
+    if (existsSync(targetDir)) {
+        throw new Error(`target directory already exists: ${targetDir}`);
+    }
+    mkdirSync(targetDir, { recursive: true, mode: 0o700 });
+    await tarExtract({ file: opts.snapshotPath, cwd: targetDir });
+    return { targetDir, entries };
+}

package/dist/render.js

@@ -0,0 +1,168 @@
+// CLI output renderer — color, tables, icons, spinner, output-mode resolution.
+//
+// Two output modes coexist across every command:
+//
+//   human  — pretty default, ANSI color when stdout is a TTY and NO_COLOR/
+//            FLAIR_NO_COLOR aren't set
+//   json   — agent-default, also auto-selected when stdout is piped
+//
+// Precedence: --json flag > FLAIR_OUTPUT=json env > non-TTY stdout > TTY (human).
+// Setting FLAIR_OUTPUT=human forces human mode even when piped.
+//
+// No third-party deps — minimal ANSI by hand keeps the dependency tree flat
+// (the rest of the flair runtime already runs ANSI-free; we don't need
+// chalk/picocolors' edge-case coverage for SGR codes we don't use).
+const stdoutIsTTY = !!process.stdout.isTTY;
+const stderrIsTTY = !!process.stderr.isTTY;
+const noColorEnv = process.env.NO_COLOR != null || process.env.FLAIR_NO_COLOR != null;
+const enableColor = stdoutIsTTY && !noColorEnv;
+const C = (code) => (enableColor ? `\x1b[${code}m` : "");
+export const c = {
+    reset: C("0"),
+    bold: C("1"),
+    dim: C("2"),
+    italic: C("3"),
+    underline: C("4"),
+    red: C("31"),
+    green: C("32"),
+    yellow: C("33"),
+    blue: C("34"),
+    magenta: C("35"),
+    cyan: C("36"),
+    white: C("37"),
+    gray: C("90"),
+};
+export function wrap(color, text) {
+    if (!color)
+        return text;
+    return `${color}${text}${c.reset}`;
+}
+export function resolveOutputMode(opts) {
+    if (opts.json)
+        return "json";
+    const envOut = process.env.FLAIR_OUTPUT;
+    if (envOut === "json")
+        return "json";
+    if (envOut === "human")
+        return "human";
+    // No explicit selection — pipe-friendly default: non-TTY stdout → json.
+    return stdoutIsTTY ? "human" : "json";
+}
+export const icons = {
+    ok: wrap(c.green, "✓"),
+    warn: wrap(c.yellow, "⚠"),
+    error: wrap(c.red, "✗"),
+    info: wrap(c.cyan, "ℹ"),
+    bullet: wrap(c.gray, "·"),
+    pending: wrap(c.gray, "○"),
+    arrow: wrap(c.gray, "→"),
+};
+// Status header: bullet + bold label. Use for top-level command titles.
+export function header(label) {
+    return wrap(c.bold, label);
+}
+// Section divider — used between groups inside one command's output.
+// Subtle line + bold label, no big ═══ banners (those compete with content).
+export function section(label) {
+    return `\n${wrap(c.bold, label)}\n${wrap(c.gray, "─".repeat(Math.min(60, label.length + 8)))}`;
+}
+// Key/value pair with aligned label. Default label width 14 cols.
+export function kv(label, value, labelWidth = 14) {
+    return `  ${wrap(c.dim, label.padEnd(labelWidth))} ${value}`;
+}
+export function table(columns, rows) {
+    if (rows.length === 0)
+        return wrap(c.dim, "  (no rows)");
+    const widths = columns.map((col) => col.label.length);
+    const cells = rows.map((row) => columns.map((col, i) => {
+        const raw = row[col.key];
+        const formatted = col.format ? col.format(raw, row) : raw == null ? "—" : String(raw);
+        // Visible-width calculation — strip our own ANSI escapes before counting
+        const visibleLen = formatted.replace(/\x1b\[[0-9;]*m/g, "").length;
+        if (visibleLen > widths[i])
+            widths[i] = visibleLen;
+        return formatted;
+    }));
+    const align = (str, width, side) => {
+        const visibleLen = str.replace(/\x1b\[[0-9;]*m/g, "").length;
+        const pad = " ".repeat(Math.max(0, width - visibleLen));
+        return side === "right" ? pad + str : str + pad;
+    };
+    const headerRow = "  " +
+        columns.map((col, i) => wrap(c.dim, align(col.label, widths[i], col.align))).join("  ");
+    const bodyRows = cells
+        .map((row) => "  " + row.map((cell, i) => align(cell, widths[i], columns[i].align)).join("  "))
+        .join("\n");
+    return `${headerRow}\n${bodyRows}`;
+}
+export function spinner(label) {
+    if (!stderrIsTTY || noColorEnv) {
+        process.stderr.write(`${label}...\n`);
+        return {
+            stop: (final) => {
+                if (final)
+                    process.stderr.write(`${final}\n`);
+            },
+            update: (next) => {
+                process.stderr.write(`${next}...\n`);
+            },
+        };
+    }
+    const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    let current = label;
+    let i = 0;
+    const handle = setInterval(() => {
+        process.stderr.write(`\r${wrap(c.cyan, frames[i])} ${current}`);
+        i = (i + 1) % frames.length;
+    }, 80);
+    return {
+        stop: (final) => {
+            clearInterval(handle);
+            process.stderr.write("\r\x1b[K");
+            if (final)
+                process.stderr.write(`${final}\n`);
+        },
+        update: (next) => {
+            current = next;
+        },
+    };
+}
+// Canonical JSON output: 2-space indent, trailing newline omitted by caller.
+export function asJSON(value) {
+    return JSON.stringify(value, null, 2);
+}
+// Bytes → human readable. Mirror of humanBytes in cli.ts; centralizing here
+// so render-aware code shares the same format.
+export function humanBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "—";
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+// ISO timestamp → "12m ago" / "2h ago" / "5d ago" / "—" (null) / fallback.
+export function relativeTime(iso) {
+    if (!iso)
+        return "—";
+    const ago = Date.now() - new Date(iso).getTime();
+    if (!Number.isFinite(ago) || ago < 0)
+        return "—";
+    const mins = Math.floor(ago / 60000);
+    const hrs = Math.floor(ago / 3600000);
+    const days = Math.floor(ago / 86400000);
+    return days > 0 ? `${days}d ago` : hrs > 0 ? `${hrs}h ago` : mins > 0 ? `${mins}m ago` : "just now";
+}
+// Convenience: print the right shape for the resolved output mode.
+// Caller passes both representations and the resolveOutputMode result.
+export function print(mode, jsonValue, humanText) {
+    if (mode === "json") {
+        console.log(asJSON(jsonValue));
+    }
+    else {
+        console.log(humanText);
+    }
+}

package/dist/resources/A2AAdapter.js

@@ -265,6 +265,17 @@ function statusFromOrgEvent(event) {
         null);
 }
 export class A2AAdapter extends Resource {
+    // A2A discovery surface — agent-card metadata (GET) is intentionally
+    // public so other agents/clients can discover this Flair as a memory
+    // peer. POST is JSON-RPC for actions (message/send writes OrgEvents,
+    // tasks/list reads Beads issues, message/stream subscribes to events)
+    // and is auth-gated upstream by auth-middleware's narrowed allow-list
+    // (GET /a2a passes through; POST /a2a must carry TPS-Ed25519 or admin
+    // Basic). The post() handler below additionally enforces sender ==
+    // params.agentId for message/send so an authenticated caller can only
+    // act AS themselves, not impersonate another agent.
+    allowRead() { return true; }
+    allowCreate() { return true; }
     async get() {
         const host = process.env.FLAIR_PUBLIC_URL || "http://localhost:9926";
         return new Response(JSON.stringify({
@@ -305,6 +316,20 @@ export class A2AAdapter extends Resource {
         }
         const id = body.id ?? null;
         const params = body.params ?? {};
+        // Defense-in-depth: auth-middleware narrows the /a2a allow-list so
+        // POSTs only reach here after TPS-Ed25519 or admin Basic succeeds,
+        // which sets request.tpsAgent / tpsAgentIsAdmin. If middleware was
+        // misconfigured or someone added a back-door allow-list entry, fail
+        // closed here. Pattern matches WorkspaceState/Memory/etc.
+        const ctx = this.getContext?.() ?? _context ?? {};
+        const ctxRequest = ctx.request ?? ctx;
+        const callerAgent = ctxRequest?.tpsAgent;
+        const callerIsAdmin = ctxRequest?.tpsAgentIsAdmin === true;
+        if (!callerAgent && !callerIsAdmin) {
+            return rpcError(id, -32001, "Unauthorized", {
+                detail: "POST /a2a requires TPS-Ed25519 or admin Basic auth",
+            });
+        }
         try {
             if (body.method === "message/stream") {
                 const agentId = cleanText(params.agentId);
@@ -402,6 +427,16 @@ export class A2AAdapter extends Resource {
                 if (!agentId || !message || typeof message !== "object") {
                     return rpcError(id, -32602, "Invalid params: agentId and message are required");
                 }
+                // Sender must match params.agentId — you can only send AS yourself.
+                // Admin agents may send as anyone (operational convenience).
+                // Without this check, an authenticated agent could forge OrgEvents
+                // attributed to any other agent — defeats the whole signed-envelopes
+                // model that delegationChain enforces for TPS mail.
+                if (!callerIsAdmin && callerAgent !== agentId) {
+                    return rpcError(id, -32001, "Forbidden", {
+                        detail: `caller ${callerAgent ?? "(anon)"} cannot send as ${agentId}`,
+                    });
+                }
                 const agent = await databases.flair.Agent.get(agentId).catch(() => null);
                 if (!agent) {
                     return rpcError(id, -32004, "Agent not found", { agentId });

package/dist/resources/Admin.js

@@ -0,0 +1,16 @@
+import { Resource } from "@harperfast/harper";
+/**
+ * GET /Admin — friendly redirect to /AdminDashboard.
+ *
+ * Operators bookmark or type the bare /Admin path. Without this resource
+ * they hit a 404 and assume the admin UI is broken. The dashboard is the
+ * canonical landing surface; redirect there.
+ */
+export class Admin extends Resource {
+    async get() {
+        return new Response("", {
+            status: 302,
+            headers: { Location: "/AdminDashboard" },
+        });
+    }
+}