@cliftonc/finius 0.1.0

package/dist/cli/doctor.js

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { intro, log, outro } from "@clack/prompts";
+import { TELEMETRY_HOOK_EVENTS } from "./claude-settings.js";
+import { CONFIG_PATH, loadConfig, normalizeUrl, resolveAuthToken } from "./config.js";
+import { isFiniusOnPath } from "./install.js";
+import { banner, pc } from "./ui.js";
+const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+// `finius doctor` — checks that the three things that must agree actually do: the configured server
+// URL, the OTEL endpoints in Claude Code's settings, and a reachable healthy server. Prints a
+// checklist and exits non-zero if anything is broken.
+export async function runDoctor() {
+    let problems = 0;
+    const ok = (label) => log.success(label);
+    const warn = (label, hint) => {
+        log.warn(`${label}${hint ? `\n${pc.dim(`→ ${hint}`)}` : ""}`);
+    };
+    const bad = (label, hint) => {
+        problems++;
+        log.error(`${label}${hint ? `\n${pc.dim(`→ ${hint}`)}` : ""}`);
+    };
+    const section = (title, detail) => log.message(pc.bold(title) + (detail ? pc.dim(`  ${detail}`) : ""));
+    banner("doctor");
+    intro(pc.bgCyan(pc.black(" Diagnostics ")));
+    // --- Config -----------------------------------------------------------------
+    section("Config", CONFIG_PATH);
+    const config = loadConfig();
+    const serverUrl = config?.serverUrl;
+    if (serverUrl)
+        ok(`serverUrl = ${serverUrl}`);
+    else
+        bad("no config found", "run `finius setup`");
+    const serverOrigin = serverUrl ? originOf(serverUrl) : null;
+    // --- Claude Code telemetry --------------------------------------------------
+    section("Claude Code telemetry", CLAUDE_SETTINGS_PATH);
+    const settings = readSettings();
+    if (!settings) {
+        bad("settings.json missing or invalid JSON", "run `finius setup`");
+    }
+    else {
+        const env = settings.env ?? {};
+        if (env.CLAUDE_CODE_ENABLE_TELEMETRY === "1")
+            ok("CLAUDE_CODE_ENABLE_TELEMETRY = 1");
+        else
+            bad("telemetry not enabled (CLAUDE_CODE_ENABLE_TELEMETRY != 1)", "run `finius setup`");
+        const metrics = env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT;
+        const logs = env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT;
+        metrics ? ok(`metrics endpoint → ${metrics}`) : bad("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT not set");
+        logs ? ok(`logs endpoint    → ${logs}`) : bad("OTEL_EXPORTER_OTLP_LOGS_ENDPOINT not set");
+        // The classic failure: endpoints point at a different origin than the server we serve/configure.
+        for (const ep of [metrics, logs].filter(Boolean)) {
+            const epOrigin = originOf(ep);
+            if (serverOrigin && epOrigin && epOrigin !== serverOrigin) {
+                bad(`endpoint ${epOrigin} does not match serverUrl ${serverOrigin}`, "re-run `finius setup` so the endpoints and the served port agree");
+            }
+        }
+        const protocol = env.OTEL_EXPORTER_OTLP_PROTOCOL ?? env.OTEL_EXPORTER_OTLP_METRICS_PROTOCOL;
+        if (protocol === "http/json")
+            ok("protocol = http/json");
+        else
+            warn(`protocol = ${protocol ?? "(unset → defaults to http/protobuf)"}`, "Finius expects http/json");
+        // Hook
+        const eventsWithHook = TELEMETRY_HOOK_EVENTS.filter((e) => (settings.hooks?.[e] ?? []).some((g) => g.hooks?.some((h) => h.command?.includes("finius"))));
+        if (eventsWithHook.length === TELEMETRY_HOOK_EVENTS.length)
+            ok(`hook installed for ${eventsWithHook.join(" + ")}`);
+        else if (eventsWithHook.length > 0)
+            warn(`hook only on ${eventsWithHook.join(", ")}`, "re-run `finius setup`");
+        else
+            bad("transcript-upload hook not installed", "run `finius setup`");
+    }
+    // --- CLI --------------------------------------------------------------------
+    section("CLI");
+    if (isFiniusOnPath())
+        ok("`finius` is on PATH");
+    else
+        warn("`finius` not on PATH", "install globally with `npm i -g finius` so hooks can run it");
+    // --- Server -----------------------------------------------------------------
+    section("Server");
+    if (serverUrl) {
+        const health = await probeHealth(`${serverUrl}/api/health`);
+        if (health.status === 200) {
+            ok(`reachable at ${serverUrl} (/api/health 200)`);
+            // --- Auth (Secure Mode) -------------------------------------------------
+            const credential = resolveAuthToken(config);
+            if (health.secure) {
+                ok("server is in Secure Mode (auth required)");
+                if (!credential) {
+                    bad("server requires auth but no credential is configured", "run `finius setup` to log in");
+                }
+                else {
+                    // Verify the credential actually authenticates against a protected endpoint.
+                    const authed = await probe(`${serverUrl}/api/meta`, credential);
+                    if (authed === 200)
+                        ok("configured credential authenticates");
+                    else if (authed === 401)
+                        bad("configured credential was rejected (401)", "re-run `finius setup` to refresh it");
+                    else
+                        warn(`couldn't verify credential (/api/meta ${authed})`);
+                }
+            }
+            else {
+                ok("server is open (no auth)");
+                if (credential)
+                    warn("a credential is configured but the server isn't in Secure Mode", "harmless, but you can clear it");
+            }
+        }
+        else {
+            bad(`not reachable at ${serverUrl} (${health.status})`, "start it with `finius serve`");
+        }
+    }
+    // --- Reminders --------------------------------------------------------------
+    log.message(pc.bold("Reminders") +
+        "\n" +
+        pc.dim("• Restart Claude Code after changing settings — env is read at startup.\n" +
+            "• Telemetry settings apply to the local CLI, not Claude Code on the web.\n" +
+            "• Metrics flush ~10s, events ~5s; give a new session a moment to report."));
+    outro(problems === 0 ? pc.green("All good.") : pc.red(`${problems} problem(s) found.`));
+    return problems === 0 ? 0 : 1;
+}
+function readSettings() {
+    if (!existsSync(CLAUDE_SETTINGS_PATH))
+        return null;
+    try {
+        return JSON.parse(readFileSync(CLAUDE_SETTINGS_PATH, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function originOf(url) {
+    try {
+        const u = new URL(normalizeUrl(url) || url);
+        return `${u.protocol}//${u.host}`;
+    }
+    catch {
+        return null;
+    }
+}
+async function probe(url, credential) {
+    try {
+        const headers = credential ? { authorization: `Bearer ${credential}` } : undefined;
+        const res = await fetch(url, { headers, signal: AbortSignal.timeout(2_000) });
+        return res.status;
+    }
+    catch (err) {
+        return err.name === "TimeoutError" ? "timeout" : "no response";
+    }
+}
+async function probeHealth(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(2_000) });
+        const body = res.ok ? (await res.json().catch(() => ({}))) : {};
+        return { status: res.status, secure: !!body.secure };
+    }
+    catch (err) {
+        return { status: err.name === "TimeoutError" ? "timeout" : "no response", secure: false };
+    }
+}

package/dist/cli/hook.js

@@ -0,0 +1,70 @@
+import { readFileSync } from "node:fs";
+import { loadConfig, resolveAuthToken, resolveServerUrl } from "./config.js";
+import { resolveIdentity } from "./identity.js";
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return ""; // run interactively with no piped input — nothing to do
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+// Invoked by Claude Code's SessionEnd / PreCompact hooks. Reads the session transcript and uploads
+// its contents to the Finius server. Always resolves with exit code 0 — a hook must never block or
+// fail Claude Code, even when the server is down.
+export async function runHook() {
+    let input = {};
+    try {
+        const raw = await readStdin();
+        if (raw.trim())
+            input = JSON.parse(raw);
+    }
+    catch {
+        return 0; // unparseable stdin — nothing actionable
+    }
+    const transcriptPath = input.transcript_path;
+    if (!transcriptPath)
+        return 0;
+    let content;
+    try {
+        content = readFileSync(transcriptPath, "utf8");
+    }
+    catch {
+        return 0; // file may have been cleaned up (e.g. a very short session)
+    }
+    if (!content.trim())
+        return 0;
+    const endpoint = `${resolveServerUrl()}/api/import/claude-hook`;
+    const headers = { "content-type": "application/json" };
+    const config = loadConfig();
+    const authToken = resolveAuthToken(config);
+    if (authToken)
+        headers.authorization = `Bearer ${authToken}`;
+    // Attribute the upload to a user (config-confirmed → live Claude account → git), so a hook-imported
+    // transcript lands under the same identity as that session's live OTEL metrics.
+    const identity = resolveIdentity("claude", config, input.cwd);
+    try {
+        const res = await fetch(endpoint, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                session_id: input.session_id,
+                transcript: content,
+                cwd: input.cwd,
+                hook_event_name: input.hook_event_name,
+                user_email: identity?.email,
+                user_account_id: identity?.accountId,
+                user_id: identity?.userId,
+                github_login: identity?.githubLogin,
+                display_name: identity?.displayName
+            }),
+            signal: AbortSignal.timeout(60_000)
+        });
+        if (!res.ok)
+            process.stderr.write(`finius hook: ${endpoint} returned ${res.status}\n`);
+    }
+    catch (err) {
+        process.stderr.write(`finius hook: upload to ${endpoint} failed (${err.message})\n`);
+    }
+    return 0;
+}

package/dist/cli/identity.js

@@ -0,0 +1,163 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+const CLAUDE_CONFIG_PATH = join(homedir(), ".claude.json");
+const CODEX_HOME = process.env.CODEX_HOME ? resolve(process.env.CODEX_HOME) : join(homedir(), ".codex");
+// --- Pure parsers (no I/O — unit-tested) ----------------------------------------------------------
+// Claude Code records the signed-in account in ~/.claude.json under `oauthAccount`. This is the same
+// account live OTEL tags as user.email / user.account_uuid / user.id, so preferring it keeps a
+// hook-imported transcript under the same identity as that session's metrics.
+export function parseClaudeAccount(raw) {
+    const json = safeParseObject(raw);
+    if (!json)
+        return null;
+    const acct = asObject(json.oauthAccount);
+    const email = asString(acct?.emailAddress);
+    const accountId = asString(acct?.accountUuid);
+    const userId = asString(json.userID);
+    const displayName = asString(acct?.displayName);
+    if (!email && !accountId && !userId)
+        return null;
+    return { email, accountId, userId, displayName, source: "claude" };
+}
+// Codex stores its ChatGPT login in ~/.codex/auth.json: `tokens.account_id` plus a JWT `id_token`
+// whose payload carries the account email. We decode the JWT payload locally (NO signature
+// verification — we only read the `email` claim for attribution, never trust it for auth).
+export function parseCodexAuth(raw) {
+    const json = safeParseObject(raw);
+    if (!json)
+        return null;
+    const tokens = asObject(json.tokens);
+    const accountId = asString(tokens?.account_id);
+    const claims = asString(tokens?.id_token) ? decodeJwtPayload(asString(tokens?.id_token)) : null;
+    const email = asString(claims?.email);
+    const displayName = asString(claims?.name);
+    if (!email && !accountId)
+        return null;
+    return { email, accountId, displayName, source: "codex" };
+}
+// Decode (WITHOUT verifying) the payload segment of a JWT. Returns null on any malformed input.
+export function decodeJwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length < 2)
+        return null;
+    try {
+        const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const json = JSON.parse(Buffer.from(b64, "base64").toString("utf8"));
+        return json && typeof json === "object" ? json : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Build an Identity from the GitHub fields `gh api user` returns. Pure so it's testable without `gh`.
+export function githubIdentity(login, name, email) {
+    if (!login && !email)
+        return null;
+    return { githubLogin: login || undefined, displayName: name || undefined, email: email || undefined, source: "github" };
+}
+// --- Live readers (filesystem / subprocess) -------------------------------------------------------
+export function readClaudeAccount() {
+    try {
+        return parseClaudeAccount(readFileSync(CLAUDE_CONFIG_PATH, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function readCodexAccount() {
+    try {
+        return parseCodexAuth(readFileSync(join(CODEX_HOME, "auth.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+// The repo-local commit identity (git config user.email) for the directory a session ran in. A weak
+// fallback — it's authorship, not an account — but universal across agents and present in any repo.
+export function readGitIdentity(cwd) {
+    const email = gitConfig("user.email", cwd);
+    if (!email)
+        return null;
+    return { email, displayName: gitConfig("user.name", cwd), source: "git" };
+}
+// GitHub identity via the `gh` CLI. `gh api user` (a network call) returns login + name + email — run
+// at setup only, never in the hot hook path. Returns null if `gh` is absent or signed out.
+export function readGithub() {
+    try {
+        const out = execFileSync("gh", ["api", "user", "--jq", "{login, name, email}"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 8_000
+        }).trim();
+        if (!out)
+            return null;
+        const json = safeParseObject(out);
+        if (!json)
+            return null;
+        return githubIdentity(asString(json.login), asString(json.name), asString(json.email));
+    }
+    catch {
+        return null;
+    }
+}
+// --- Resolution -----------------------------------------------------------------------------------
+// Resolve the identity to attach to an upload, honoring the setup-confirmed config first, then a live
+// account read, then the repo's git identity. The shared GitHub login/display name (captured at setup)
+// are layered on regardless of which slot won, so the server `users` table can be enriched with them.
+export function resolveIdentity(kind, config, cwd) {
+    const stored = kind === "claude" ? config?.identity?.claude : config?.identity?.codex;
+    const live = kind === "claude" ? readClaudeAccount() : readCodexAccount();
+    const base = fromStored(stored) ?? live ?? readGitIdentity(cwd);
+    const githubLogin = config?.identity?.githubLogin;
+    const displayName = config?.identity?.displayName;
+    if (!base) {
+        if (!githubLogin && !displayName)
+            return null;
+        return { githubLogin, displayName, source: "github" };
+    }
+    return {
+        ...base,
+        githubLogin: base.githubLogin ?? githubLogin,
+        displayName: base.displayName ?? displayName
+    };
+}
+function fromStored(stored) {
+    if (!stored)
+        return null;
+    const { email, accountId, userId } = stored;
+    if (!email && !accountId && !userId)
+        return null;
+    return { email, accountId, userId, source: "config" };
+}
+// --- Small narrowing helpers ----------------------------------------------------------------------
+function safeParseObject(raw) {
+    try {
+        const v = JSON.parse(raw);
+        return v && typeof v === "object" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+function asObject(v) {
+    return v && typeof v === "object" ? v : undefined;
+}
+function asString(v) {
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function gitConfig(key, cwd) {
+    try {
+        const out = execFileSync("git", ["config", "--get", key], {
+            cwd: cwd && existsSync(cwd) ? cwd : undefined,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2_000
+        }).trim();
+        return out || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cli/import.js

@@ -0,0 +1,61 @@
+import { intro, outro, select, spinner } from "@clack/prompts";
+import { backfill, findClaudeTranscripts } from "./backfill.js";
+import { CODEX_SOURCE, findCodexRollouts } from "./codex.js";
+import { resolveServerUrl } from "./config.js";
+import { ask, banner, pc } from "./ui.js";
+export async function runImport(args = []) {
+    banner("import");
+    intro(pc.bgCyan(pc.black(" Import historical sessions ")));
+    const target = await resolveTarget(args[0]);
+    if (!target) {
+        process.stderr.write(`${pc.red(`Unknown import target: ${args[0]}`)}\n`);
+        process.stderr.write(`Use ${pc.cyan("finius import claude")}, ${pc.cyan("finius import codex")}, or ${pc.cyan("finius import all")}.\n`);
+        return 1;
+    }
+    const serverUrl = resolveServerUrl();
+    if (!(await checkServer(serverUrl))) {
+        outro(pc.yellow(`Server not reachable at ${serverUrl}. Start it with \`finius serve\`, then re-run import.`));
+        return 1;
+    }
+    let failed = 0;
+    if (target === "claude" || target === "all") {
+        failed += (await backfill(findClaudeTranscripts(), { source: "claude-code-jsonl", format: "claude", label: "Claude sessions" })).failed;
+    }
+    if (target === "codex" || target === "all") {
+        failed += (await backfill(findCodexRollouts(), { source: CODEX_SOURCE, format: "codex", label: "Codex sessions" })).failed;
+    }
+    outro(failed ? pc.yellow("Import finished with failures.") : pc.green("Import finished."));
+    return failed ? 1 : 0;
+}
+async function resolveTarget(value) {
+    if (!value) {
+        return ask(await select({
+            message: "Which historical sessions should be imported?",
+            options: [
+                { value: "all", label: "Claude + Codex" },
+                { value: "claude", label: "Claude only" },
+                { value: "codex", label: "Codex only" }
+            ]
+        }));
+    }
+    const normalized = value.toLowerCase();
+    if (normalized === "claude" || normalized === "codex" || normalized === "all")
+        return normalized;
+    return null;
+}
+async function checkServer(serverUrl) {
+    const s = spinner();
+    s.start(`Checking server at ${serverUrl}`);
+    try {
+        const res = await fetch(`${serverUrl}/api/health`, { signal: AbortSignal.timeout(2_000) });
+        if (res.ok) {
+            s.stop(`Server reachable at ${pc.cyan(serverUrl)}`);
+            return true;
+        }
+        s.stop(pc.yellow(`Server responded with ${res.status}`));
+    }
+    catch {
+        s.stop(pc.yellow("Server not reachable"));
+    }
+    return false;
+}

package/dist/cli/index.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { runCodexHook } from "./codex.js";
+import { CONFIG_PATH, configExists, loadConfig } from "./config.js";
+import { runDoctor } from "./doctor.js";
+import { runHook } from "./hook.js";
+import { runImport } from "./import.js";
+import { runServe } from "./serve.js";
+import { runSetup } from "./setup.js";
+import { banner, pc } from "./ui.js";
+const COMMANDS = [
+    ["finius", "Run setup if not configured, otherwise show status & help"],
+    ["finius setup [url]", "Configure server URL + Claude Code telemetry env & hook"],
+    ["finius import [claude|codex|all]", "Import historical Claude/Codex sessions only"],
+    ["finius serve [--port N]", "Start the Finius server (API + dashboard)"],
+    ["finius doctor", "Diagnose telemetry/hook/server config and connectivity"],
+    ["finius hook", "Internal: upload the current session transcript (run by Claude Code hooks)"],
+    ["finius codex-hook", "Internal: upload the current Codex rollout (run by the Codex Stop hook)"],
+    ["finius help", "Show this help"]
+];
+function helpText() {
+    const width = Math.max(...COMMANDS.map(([cmd]) => cmd.length));
+    const rows = COMMANDS.map(([cmd, desc]) => `  ${pc.cyan(cmd.padEnd(width))}  ${pc.dim(desc)}`).join("\n");
+    return `${pc.bold("Usage")}\n${rows}\n\n${pc.dim("Config:")} ${CONFIG_PATH}\n`;
+}
+function printStatus() {
+    banner();
+    const config = loadConfig();
+    process.stdout.write(`\n${pc.green("Finius is configured.")}\n\n`);
+    process.stdout.write(`  ${pc.dim("Server URL")}  ${config?.serverUrl ?? "(unknown)"}\n`);
+    process.stdout.write(`  ${pc.dim("Config")}      ${CONFIG_PATH}\n\n`);
+    process.stdout.write(`Run ${pc.cyan("finius setup")} to change settings, or ${pc.cyan("finius serve")} to start the server.\n\n`);
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case undefined:
+            if (!configExists())
+                return runSetup();
+            printStatus();
+            process.stdout.write(helpText());
+            return 0;
+        case "setup":
+            return runSetup(rest);
+        case "serve":
+            return runServe(rest);
+        case "doctor":
+            return runDoctor();
+        case "import":
+            return runImport(rest);
+        case "hook":
+            return runHook();
+        case "codex-hook":
+            return runCodexHook();
+        case "help":
+        case "--help":
+        case "-h":
+            banner();
+            process.stdout.write(`\n${helpText()}`);
+            return 0;
+        default:
+            process.stderr.write(`${pc.red(`Unknown command: ${cmd}`)}\n\n${helpText()}`);
+            return 1;
+    }
+}
+main()
+    .then((code) => process.exit(code ?? 0))
+    .catch((err) => {
+    process.stderr.write(`finius: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/cli/install.js

@@ -0,0 +1,23 @@
+import { execSync } from "node:child_process";
+// Is the `finius` command resolvable on PATH? (i.e. installed globally, not just running via npx)
+export function isFiniusOnPath() {
+    const probe = process.platform === "win32" ? "where finius" : "command -v finius";
+    try {
+        execSync(probe, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Install finius globally so the bare `finius` command works everywhere (including from Claude Code
+// hooks). Returns true once `finius` is on PATH. Output is streamed so the user sees npm's progress.
+export function installGlobally() {
+    try {
+        execSync("npm install -g @cliftonc/finius", { stdio: "inherit" });
+    }
+    catch {
+        return false;
+    }
+    return isFiniusOnPath();
+}

package/dist/cli/password.js

@@ -0,0 +1,14 @@
+import { randomBytes, randomInt } from "node:crypto";
+import { adjectives, animals, colors } from "unique-names-generator";
+// Generate a memorable word-password like `blue-happy-otter` for Secure Mode. We draw the words from
+// unique-names-generator's curated dictionaries but pick with node:crypto (randomInt) rather than the
+// library's Math.random-based generator, so the password is cryptographically random — it guards a
+// server. Three words from these lists is ~30 bits; the real protection is that it's only ever used
+// once to mint a revocable session token (it never travels on normal requests).
+export function generatePassword() {
+    const pick = (list) => list[randomInt(list.length)];
+    return [pick(colors), pick(adjectives), pick(animals)].join("-").toLowerCase();
+}
+export function generateAuthToken() {
+    return randomBytes(32).toString("hex");
+}

package/dist/cli/serve.js

@@ -0,0 +1,63 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { FINIUS_HOME, loadConfig, saveConfig } from "./config.js";
+import { startServer } from "../server/index.js";
+import { generateAuthToken } from "./password.js";
+// `finius serve [--port N]` — start the single-process server (API + built dashboard). Data is kept
+// under ~/.finius by default so an `npx`/globally-installed CLI has a stable home, independent of cwd.
+export async function runServe(argv) {
+    let port;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if ((arg === "--port" || arg === "-p") && argv[i + 1])
+            port = Number(argv[++i]);
+        else if (arg.startsWith("--port="))
+            port = Number(arg.slice("--port=".length));
+    }
+    if (port !== undefined && !Number.isInteger(port)) {
+        process.stderr.write("finius serve: --port must be an integer\n");
+        return 1;
+    }
+    // Without an explicit --port, bind to the port from the configured server URL (set in `finius
+    // setup`) so the dashboard the CLI points users at is the one we actually serve.
+    if (port === undefined)
+        port = portFromConfig();
+    const dataDir = join(FINIUS_HOME, "data");
+    mkdirSync(dataDir, { recursive: true });
+    // Secure Mode: if `finius setup` saved a master password on this (owner) machine, run the server
+    // locked. An explicit env var still wins (handy for one-off overrides).
+    const config = loadConfig();
+    const authSecret = process.env.FINIUS_AUTH_PASSWORD ?? config?.authPassword;
+    let initialAuthToken = config?.authToken;
+    if (authSecret && config?.authPassword && !initialAuthToken) {
+        initialAuthToken = generateAuthToken();
+        saveConfig({ ...config, authToken: initialAuthToken });
+    }
+    startServer({
+        port,
+        dbPath: process.env.FINIUS_DB_PATH ?? join(dataDir, "finius.sqlite"),
+        blobDir: process.env.FINIUS_BLOB_DIR ?? join(FINIUS_HOME, "transcripts"),
+        authSecret,
+        initialAuthToken
+    });
+    // The server runs until the process is signalled. Never resolve, so the CLI entrypoint doesn't
+    // `process.exit()` out from under the listening server. startServer() installs SIGINT/SIGTERM
+    // handlers that close the DB and exit cleanly.
+    await new Promise(() => { });
+    return 0; // unreachable
+}
+// Derive the listen port from the saved serverUrl (e.g. http://localhost:8787 → 8787).
+function portFromConfig() {
+    const config = loadConfig();
+    if (!config)
+        return undefined;
+    try {
+        const url = new URL(config.serverUrl);
+        if (url.port)
+            return Number(url.port);
+        return url.protocol === "https:" ? 443 : 80;
+    }
+    catch {
+        return undefined;
+    }
+}