neagen 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+Neagen CLI — Proprietary License
+Copyright (c) 2026 Neagen. All rights reserved.
+
+This software and its source code are proprietary and confidential.
+
+You are permitted to download, install, and run the official `neagen` package
+from the public npm registry for the sole purpose of accessing the Neagen
+service.
+
+You are NOT permitted to copy, reproduce, modify, adapt, translate, reverse
+engineer, decompile, merge, publish, redistribute, sublicense, sell, or create
+derivative works of this software or any part of its source code, in whole or
+in part, except with the prior express written permission of the copyright
+holder.
+
+No rights or licenses are granted except as expressly stated above. All other
+rights are reserved by the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# neagen
+
+Your personal **networking agent**, in the terminal.
+
+State a need, and your Neagen remembers who you know, finds the right person
+across your network, and prepares a warm introduction — you review and approve
+every outbound. The CLI is a thin, secure client for your hosted Neagen.
+
+## Install & run
+
+```bash
+npx neagen
+```
+
+…or install it once and run `neagen` anytime:
+
+```bash
+npm install -g neagen
+neagen
+```
+
+Requires **Node.js 24+**.
+
+## First time
+
+1. Create your account on the web at **https://neagen.xyz** (passkey — no
+   password).
+2. Run `neagen`. It opens your browser to approve the terminal with your
+   passkey, then drops you into your agent.
+
+The CLI can only sign in to an **existing** account — it can never create one.
+Your passkey stays the root of your identity.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `neagen` | Open your agent (logs you in on first run) |
+| `neagen login` | Log in / refresh your session, then exit |
+| `neagen logout` | Forget the saved session on this machine |
+| `neagen doctor` | Check connectivity + login status |
+| `neagen --version` | Print the version |
+| `neagen --help` | Show help |
+
+## Environment
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `NEAGEN_HOST` | `https://neagen.xyz` | Server to connect to (local dev: `http://localhost:3000`) |
+| `NEAGEN_PROFILE` | _(main)_ | Named credential slot, e.g. for multiple accounts |
+
+## Where your session is stored
+
+A normal session token is cached at `~/.neagen/credentials.json` with
+owner-only permissions (`0600`). Remove it anytime with `neagen logout`.
+
+## License
+
+Proprietary — © 2026 Neagen, all rights reserved. You may install and run this
+package to access the Neagen service; you may not copy, modify, or redistribute
+it. See [LICENSE](./LICENSE).

package/lib/api.mjs

@@ -0,0 +1,56 @@
+const DEFAULT_TIMEOUT_MS = 8_000;
+
+export async function probeHost(host) {
+  const res = await fetch(`${host}/eve/v1/health`, {
+    signal: AbortSignal.timeout(5_000),
+  });
+  if (!res.ok) throw new Error(`health ${res.status}`);
+  return true;
+}
+
+export async function apiFetch(host, path, { token, method = "GET", body } = {}) {
+  const res = await fetch(`${host}${path}`, {
+    method,
+    headers: {
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+      ...(body ? { "content-type": "application/json" } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+  });
+  const data = await res.json().catch(() => null);
+  return { res, data };
+}
+
+/** Resolve owner identity — /api/me when deployed, else Ably token clientId. */
+export async function resolveIdentity(host, token) {
+  const me = await apiFetch(host, "/api/me", { token });
+  if (me.res.ok && me.data?.ownerId) {
+    return {
+      ownerId: me.data.ownerId,
+      displayName: me.data.displayName ?? "you",
+      neagenName: me.data.neagenName ?? "Neagen",
+    };
+  }
+  if (me.res.status !== 404 && me.res.status !== 401) {
+    const msg = me.data?.error?.message ?? `HTTP ${me.res.status}`;
+    throw new Error(msg);
+  }
+  if (me.res.status === 401) return null;
+
+  const ably = await apiFetch(host, "/api/ably-token", { token });
+  if (ably.res.ok && ably.data?.clientId) {
+    return {
+      ownerId: ably.data.clientId,
+      displayName: "you",
+      neagenName: "Neagen",
+    };
+  }
+  if (ably.res.status === 401) return null;
+
+  throw new Error(
+    me.res.status === 404
+      ? "Server is missing /api/me — deploy latest Neagen, or check ABLY_API_KEY on the server."
+      : (ably.data?.error?.message ?? `identity check failed (${ably.res.status})`),
+  );
+}

package/lib/creds.mjs

@@ -0,0 +1,133 @@
+// Credential + host resolution for the published `neagen` CLI.
+//
+// The CLI is a REMOTE client: it never boots a server, it talks to a deployed
+// Neagen over HTTPS. By default that is production (neagen.xyz). A session token
+// (a normal Better Auth session, minted by the RFC 8628 device grant) is cached
+// per profile under ~/.neagen with owner-only permissions, and is BOUND to the
+// host it was minted for — it is never replayed to a different origin.
+
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CRED_DIR = join(homedir(), ".neagen");
+const DEFAULT_HOST = "https://neagen.xyz";
+
+export function credPath(profile) {
+  const name = profile?.trim() ? `credentials-${profile.trim()}.json` : "credentials.json";
+  return join(CRED_DIR, name);
+}
+
+/**
+ * Host selection (published CLI):
+ *   1. NEAGEN_HOST (explicit — used for local dev against http://localhost:3000
+ *      and for self-hosters)
+ *   2. https://neagen.xyz (production default)
+ */
+export function resolveHost(overrideHost) {
+  const explicit = overrideHost?.trim() || process.env.NEAGEN_HOST?.trim();
+  if (explicit) return explicit;
+  return DEFAULT_HOST;
+}
+
+function hostnameOf(host) {
+  try {
+    return new URL(host).hostname.replace(/^\[/, "").replace(/\]$/, "");
+  } catch {
+    return "";
+  }
+}
+
+export function isLoopbackHost(host) {
+  const h = hostnameOf(host);
+  return h === "localhost" || h === "127.0.0.1" || h === "::1";
+}
+
+/**
+ * Fail closed before any token leaves this machine.
+ *
+ * The CLI sends a bearer session token to the resolved host, so refuse to send
+ * it (a) to a malformed/non-http(s) host, or (b) over plaintext http:// to a
+ * NON-loopback host (which would expose the token to the network). http:// is
+ * allowed only for localhost/127.0.0.1/::1 (local dev).
+ */
+export function assertTransportSafe(host) {
+  let url;
+  try {
+    url = new URL(host);
+  } catch {
+    throw new Error(`NEAGEN_HOST is not a valid URL: ${host}`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error(`NEAGEN_HOST must be http(s): got ${url.protocol}`);
+  }
+  if (url.protocol === "http:" && !isLoopbackHost(host)) {
+    throw new Error(
+      `Refusing to send your login token over plain http:// to a non-local host (${host}).\n` +
+        `  Use https://, or http:// only for localhost.`,
+    );
+  }
+}
+
+export function readCreds(profile) {
+  try {
+    return JSON.parse(readFileSync(credPath(profile), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function saveCreds(profile, { host, accessToken }) {
+  mkdirSync(CRED_DIR, { recursive: true, mode: 0o700 });
+  // Enforce owner-only perms even if ~/.neagen already existed with a looser
+  // mode (the mkdir `mode` is honored only on creation).
+  try {
+    chmodSync(CRED_DIR, 0o700);
+  } catch {
+    /* best-effort */
+  }
+  const target = credPath(profile);
+  const tmp = `${target}.${process.pid}.tmp`;
+  // Atomic write: a 0600 temp file then rename over the target, so a concurrent
+  // reader never sees a partial token and a pre-existing loose-perms file can't
+  // linger readable through an in-place rewrite.
+  writeFileSync(
+    tmp,
+    JSON.stringify({ host: host.trim(), access_token: accessToken }, null, 2),
+    { mode: 0o600 },
+  );
+  try {
+    chmodSync(tmp, 0o600);
+  } catch {
+    /* best-effort */
+  }
+  renameSync(tmp, target);
+}
+
+/**
+ * Return the cached token ONLY if it was minted for the host we're about to talk
+ * to. A token saved for neagen.xyz is never handed to a different NEAGEN_HOST —
+ * this is what stops a poisoned env var (`NEAGEN_HOST=https://evil neagen`) from
+ * exfiltrating a production session token. A mismatch returns null → re-login.
+ */
+export function loadToken(profile, host = resolveHost()) {
+  const creds = readCreds(profile);
+  if (!creds?.access_token) return null;
+  if (creds.host && creds.host.trim() !== host.trim()) return null;
+  return creds.access_token;
+}
+
+export function clearCreds(profile) {
+  try {
+    unlinkSync(credPath(profile));
+  } catch {
+    /* already gone */
+  }
+}

package/lib/device-login.mjs

@@ -0,0 +1,136 @@
+// Better Auth device grant (RFC 8628) — passwordless CLI login.
+//
+// The CLI requests a user_code, opens the browser to the passkey-authenticated
+// approval page (${host}/device), and polls ${host}/api/auth/device/token until
+// the Owner approves. The grant only ever mints a session for an ALREADY-EXISTING
+// account — it can never create one — so a brand-new user must first create their
+// account on the web (the /device page bounces them to sign-up). Passkey stays the
+// identity root.
+
+import { execFile } from "node:child_process";
+import { saveCreds } from "./creds.mjs";
+import { panel } from "./flow.mjs";
+
+function openBrowser(url) {
+  // Validate the scheme before handing the URL to an OS opener — never launch a
+  // javascript:/file:/custom-scheme URL, and only ever an http(s) link. The code
+  // is also printed to stderr, so a refused auto-open never blocks login.
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return;
+
+  const platform = process.platform;
+  if (platform === "darwin") execFile("open", [url], () => {});
+  // Windows: rundll32's URL handler opens the link with NO shell/cmd parsing, so
+  // a server-controlled URL can't inject into cmd.exe (the `cmd /c start` opener
+  // does parse `&`, `^`, etc.).
+  else if (platform === "win32")
+    execFile("rundll32", ["url.dll,FileProtocolHandler", url], () => {});
+  else execFile("xdg-open", [url], () => {});
+}
+
+/**
+ * A console-backed stand-in for the Eve TerminalRenderer panel, so `neagen login`
+ * and `neagen doctor` can run the grant without constructing the full TUI.
+ */
+function consoleUi() {
+  return {
+    begin(title) {
+      if (title) process.stderr.write(`\n  ${title}\n`);
+    },
+    renderLine(message) {
+      process.stderr.write(`  ${message}\n`);
+    },
+    setStatus() {},
+    end() {},
+  };
+}
+
+/**
+ * Run the RFC 8628 device grant. Pass an Eve `renderer` to draw inside its panel
+ * (the TUI path), or omit it for the plain console output (`neagen login`).
+ * @returns {Promise<string>} access token
+ */
+export async function runDeviceGrantLogin({ host, profile, renderer }) {
+  const ui = renderer ? panel(renderer) : consoleUi();
+  ui.begin("Log in to Neagen", "pulse");
+  let preserveDiagnostics = true;
+  try {
+    const codeRes = await fetch(`${host}/api/auth/device/code`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ client_id: "neagen-cli" }),
+    });
+    if (!codeRes.ok) {
+      const body = await codeRes.text();
+      ui.renderLine(`Could not start login (${codeRes.status}).`, "error");
+      if (codeRes.status === 404) {
+        ui.renderLine(
+          "CLI login is not available on this server yet.",
+          "warning",
+        );
+        console.error(
+          "\n  CLI device login returned 404 on " +
+            host +
+            ".\n  The server is reachable but does not expose the device-login endpoints.\n  (Local dev: run `npm run dev`, then `NEAGEN_HOST=http://localhost:3000 neagen`.)\n",
+        );
+      }
+      throw new Error(body || `device/code ${codeRes.status}`);
+    }
+    const code = await codeRes.json();
+
+    ui.renderLine(`Your code:  ${code.user_code}`, "info");
+    ui.renderLine(code.verification_uri_complete, "info");
+    ui.renderLine("Opening your browser — approve with your passkey…", "info");
+    // Mirror to stderr so login is never silent if the panel hasn't painted yet.
+    console.error(
+      `\n  Your code:   ${code.user_code}\n  Approve at:  ${code.verification_uri_complete}\n`,
+    );
+    openBrowser(code.verification_uri_complete);
+
+    const intervalMs = (code.interval ?? 5) * 1000;
+    const deadline = Date.now() + (code.expires_in ?? 600) * 1000;
+
+    while (Date.now() < deadline) {
+      ui.setStatus("Waiting for passkey approval…");
+      await new Promise((r) => setTimeout(r, intervalMs));
+
+      const tokRes = await fetch(`${host}/api/auth/device/token`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          device_code: code.device_code,
+          client_id: "neagen-cli",
+        }),
+      });
+
+      if (tokRes.ok) {
+        const tok = await tokRes.json();
+        saveCreds(profile, { host, accessToken: tok.access_token });
+        ui.renderLine("Logged in.", "success");
+        preserveDiagnostics = false;
+        return tok.access_token;
+      }
+
+      const err = await tokRes.json().catch(() => ({}));
+      if (err.error === "authorization_pending" || err.error === "slow_down") continue;
+
+      ui.renderLine(
+        `Login failed: ${err.error_description ?? err.error ?? tokRes.status}`,
+        "error",
+      );
+      throw new Error(err.error_description ?? err.error ?? "device/token failed");
+    }
+
+    ui.renderLine("The code expired before approval. Run neagen again.", "error");
+    throw new Error("device code expired");
+  } finally {
+    ui.setStatus(undefined);
+    ui.end({ preserveDiagnostics });
+  }
+}

package/lib/flow.mjs

@@ -0,0 +1,4 @@
+/** Eve TerminalRenderer panel API (begin/renderLine/setStatus/end live on setupFlow). */
+export function panel(renderer) {
+  return renderer.setupFlow;
+}

package/lib/tui.mjs

@@ -0,0 +1,173 @@
+// neagen TUI — chat, agent-mail, files against the deployed agent.
+// Login happens here (device-grant panel) when no valid session exists.
+//
+// Resolves Eve's TUI internals from the INSTALLED `eve` package (via
+// require.resolve), so it works no matter where npm puts the dependency — global
+// install, npx cache, or this repo's node_modules. `eve` is a hard dependency of
+// this package (see ../package.json), pinned to an exact version because these
+// dist paths are internal to that version.
+
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Client } from "eve/client";
+import { assertTransportSafe, clearCreds, loadToken, resolveHost } from "./creds.mjs";
+import { probeHost, resolveIdentity } from "./api.mjs";
+import { runDeviceGrantLogin } from "./device-login.mjs";
+import { panel } from "./flow.mjs";
+import { subscribeInboxWakeAbly } from "./wake.mjs";
+
+const require = createRequire(import.meta.url);
+// `eve` exposes "./package.json" in its exports map, so this resolves the
+// installed package root regardless of hoisting.
+const EVE_DIST = join(dirname(require.resolve("eve/package.json")), "dist", "src");
+const EVE_TUI = join(EVE_DIST, "cli", "dev", "tui");
+
+const profile = process.env.NEAGEN_PROFILE?.trim() || undefined;
+const host = resolveHost();
+
+if (!process.stdin.isTTY || !process.stdout.isTTY) {
+  console.error("neagen requires an interactive terminal.");
+  process.exit(1);
+}
+
+try {
+  assertTransportSafe(host);
+} catch (e) {
+  console.error(`\n  ${e.message}\n`);
+  process.exit(1);
+}
+
+async function importEve(relPath) {
+  return import(pathToFileURL(join(EVE_DIST, relPath)).href);
+}
+
+const [
+  { EveTUIRunner },
+  { createPromptCommandHandler },
+  { promptCommandsFor },
+  { formatRemoteAuthChallengeMessage },
+  { toErrorMessage },
+  { isVercelAuthChallenge },
+  { TerminalRenderer },
+] = await Promise.all([
+  import(pathToFileURL(join(EVE_TUI, "runner.js")).href),
+  import(pathToFileURL(join(EVE_TUI, "prompt-command-handler.js")).href),
+  import(pathToFileURL(join(EVE_TUI, "prompt-commands.js")).href),
+  import(pathToFileURL(join(EVE_TUI, "remote-auth-result.js")).href),
+  importEve("shared/errors.js"),
+  importEve("services/dev-client/vercel-auth-error.js"),
+  import(pathToFileURL(join(EVE_TUI, "terminal-renderer.js")).href),
+]);
+
+const target = {
+  kind: "remote",
+  serverUrl: host,
+  workspaceRoot: process.cwd(),
+};
+
+const renderer = new TerminalRenderer({ availablePromptCommands: promptCommandsFor("remote") });
+
+function fail(message) {
+  try {
+    panel(renderer).renderLine(message, "error");
+  } catch {
+    console.error(`\n  ${message}\n`);
+  }
+  process.exit(1);
+}
+
+async function ensureReachable() {
+  const ui = panel(renderer);
+  ui.begin("neagen", "pulse");
+  ui.renderLine(`Connecting to ${host}…`, "info");
+  try {
+    await probeHost(host);
+    ui.renderLine("Agent online.", "success");
+  } catch (e) {
+    ui.renderLine(`Can't reach ${host} (${e.message}).`, "error");
+    ui.renderLine("Check your connection, or set NEAGEN_HOST to your server.", "info");
+    ui.end({ preserveDiagnostics: true });
+    process.exit(1);
+  }
+  ui.end({ preserveDiagnostics: false });
+}
+
+async function ensureAuthenticated() {
+  let token = loadToken(profile);
+  if (token) {
+    const identity = await resolveIdentity(host, token);
+    if (identity) return { token, me: identity };
+    clearCreds(profile);
+    token = null;
+  }
+  token = await runDeviceGrantLogin({ host, profile, renderer });
+  const me = await resolveIdentity(host, token);
+  if (!me) {
+    clearCreds(profile);
+    fail("Session could not be verified after login.");
+  }
+  return { token, me };
+}
+
+await ensureReachable();
+
+let session;
+try {
+  session = await ensureAuthenticated();
+} catch (e) {
+  fail(e.message ?? "Login failed.");
+}
+
+const { me } = session;
+const label = me.displayName ?? "you";
+const ownerId = me.ownerId;
+
+const client = new Client({
+  host,
+  auth: { bearer: () => loadToken(profile) ?? "" },
+  preserveCompletedSessions: true,
+});
+
+try {
+  await client.health();
+} catch (e) {
+  fail(`Agent unreachable at ${host} (${e.message}).`);
+}
+
+let wake;
+try {
+  const token = loadToken(profile);
+  wake = await subscribeInboxWakeAbly(ownerId, (ev) => {
+    const what = ev.kind === "message" ? "a message" : `a file (${ev.filename})`;
+    renderer.renderNotice(
+      `📬 New mail — ${what} arrived. Ask me about it (e.g. "what's new?") to fetch it.`,
+    );
+  }, { host, bearerToken: token });
+} catch {
+  /* wake is best-effort */
+}
+
+const stopWake = async () => {
+  try {
+    await wake?.close();
+  } catch {
+    /* best-effort */
+  }
+};
+process.on("SIGINT", stopWake);
+process.on("exit", () => void wake?.close());
+
+await new EveTUIRunner({
+  name: `neagen (${label})`,
+  session: client.session(),
+  client,
+  serverUrl: host,
+  renderer,
+  promptCommandHandler: createPromptCommandHandler({ target }),
+  availablePromptCommands: promptCommandsFor("remote"),
+  formatTransportError: (error) =>
+    isVercelAuthChallenge(error) ? formatRemoteAuthChallengeMessage(host) : toErrorMessage(error),
+}).run();
+
+await stopWake();

package/lib/wake.mjs

@@ -0,0 +1,312 @@
+// Plain-ESM mailbox watcher / wake subscriber for the node scripts (CLI / TUI /
+// live demo). Canonical home for the script-side wake client.
+//
+// This is the script-side twin of src/lib/agentmail/wake.ts (the TS module used
+// by the app + vitest). The node entrypoints are .mjs and can't import the TS
+// path-aliased module, so the same ~40 lines live here. Keep the two in sync.
+//
+// The published `neagen` CLI uses ONLY subscribeInboxWakeAbly (token auth against
+// /api/ably-token). The fs/ws transports below are for local dev / the two-agent
+// harness and are inert in the remote CLI.
+//
+// The wake is non-polling: fs.watch is OS-level (FSEvents / inotify), event-
+// driven. "Mail = the file system" — a wake is just an envelope appearing in the
+// recipient's transit mailbox.
+
+import { watch } from "node:fs";
+import { mkdir, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+function transitRoot() {
+  return path.resolve(process.env.AGENT_MAIL_TRANSIT_DIR || ".agent-mail-transit");
+}
+
+export function ownerMailboxDir(ownerId) {
+  return path.join(transitRoot(), ownerId);
+}
+
+async function listEnvelopes(ownerId) {
+  const dir = ownerMailboxDir(ownerId);
+  let names;
+  try {
+    names = (await readdir(dir)).filter((n) => n.endsWith(".json")).sort();
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    try {
+      out.push(JSON.parse(await readFile(path.join(dir, name), "utf8")));
+    } catch {
+      // skip a partial/corrupt envelope until it is complete
+    }
+  }
+  return out;
+}
+
+/**
+ * Watch an owner's transit mailbox; call onWake once per NEW envelope.
+ * Returns { close() }. Event-driven (fs.watch), de-duped by envelope id, drains
+ * pre-existing mail on subscribe unless drainExisting === false.
+ */
+export async function subscribeInboxWake(ownerId, onWake, { drainExisting = true } = {}) {
+  const dir = ownerMailboxDir(ownerId);
+  await mkdir(dir, { recursive: true });
+
+  const seen = new Set();
+  let closed = false;
+  let draining = false;
+  let rerun = false;
+  let firstDrain = true;
+
+  const drainOnce = async () => {
+    if (closed) return;
+    const suppress = firstDrain && !drainExisting;
+    firstDrain = false;
+    const pending = await listEnvelopes(ownerId);
+    for (const env of pending) {
+      if (seen.has(env.id)) continue;
+      seen.add(env.id);
+      if (suppress) continue;
+      try {
+        await onWake({
+          toOwnerId: env.toOwnerId,
+          fromOwnerId: env.fromOwnerId,
+          kind: env.kind ?? "file",
+          filename: env.filename,
+          envelopeId: env.id,
+        });
+      } catch {
+        // a handler error must not kill the watcher
+      }
+    }
+  };
+
+  const scheduleDrain = () => {
+    if (closed) return;
+    if (draining) {
+      rerun = true;
+      return;
+    }
+    draining = true;
+    drainOnce().finally(() => {
+      draining = false;
+      if (rerun && !closed) {
+        rerun = false;
+        scheduleDrain();
+      }
+    });
+  };
+
+  await drainOnce();
+
+  let watcher;
+  try {
+    watcher = watch(dir, { persistent: true }, () => scheduleDrain());
+    watcher.on("error", () => {});
+  } catch {
+    // inert subscription if the OS can't watch; the initial drain still ran
+  }
+
+  return {
+    async close() {
+      closed = true;
+      watcher?.close();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// WS transport — the held-connection wake (production shape).
+//
+// Plain-ESM twin of src/lib/agentmail/wake-ws.ts. SAME (ownerId, onWake) ->
+// { close() } contract as subscribeInboxWake above, so the CLI/TUI handlers are
+// unchanged. Holds ONE WebSocket to the eve wake channel; the server pushes each
+// wake down it (no polling). Reconnect = offline catch-up (the server re-drains
+// transit on connect). Owner identity rides the upgrade as the x-neagen-owner
+// header — Node's native WebSocket forwards { headers } on the handshake.
+
+function wakeWsUrl(host) {
+  return host.replace(/\/+$/, "").replace(/^http/, "ws") + "/eve/v1/wake";
+}
+
+export async function subscribeInboxWakeWS(
+  ownerId,
+  onWake,
+  { host, reconnectMs = 1000, maxReconnectMs = 30000 } = {},
+) {
+  const base = host || process.env.EVE_HOST || "http://127.0.0.1:4010";
+  const url = wakeWsUrl(base);
+
+  let closed = false;
+  let socket;
+  let reconnectTimer;
+  let backoffMs = reconnectMs;
+
+  const connect = () => {
+    if (closed) return;
+    socket = new WebSocket(url, { headers: { "x-neagen-owner": ownerId } });
+    socket.onopen = () => {
+      backoffMs = reconnectMs; // a live connection resets the backoff
+    };
+    socket.onmessage = (ev) => {
+      let msg;
+      try {
+        msg = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
+      } catch {
+        return;
+      }
+      if (msg?.type === "wake" && msg.event) {
+        try {
+          const r = onWake(msg.event);
+          if (r && typeof r.then === "function") r.catch(() => {});
+        } catch {
+          // a handler error must not kill the subscription
+        }
+      }
+    };
+    socket.onclose = () => {
+      if (closed) return;
+      // Exponential backoff (NOT interval polling): one-shot timer that doubles
+      // up to the cap and resets on the next successful open.
+      reconnectTimer = setTimeout(connect, backoffMs);
+      backoffMs = Math.min(backoffMs * 2, maxReconnectMs);
+    };
+    socket.onerror = () => {
+      // onclose follows; reconnect handled there
+    };
+  };
+
+  connect();
+
+  await new Promise((resolve) => {
+    if (!socket || socket.readyState === WebSocket.OPEN) return resolve();
+    socket.addEventListener("open", () => resolve(), { once: true });
+    setTimeout(resolve, 1500);
+  });
+
+  return {
+    async close() {
+      closed = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      try {
+        socket?.close();
+      } catch {
+        // already closing
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Ably transport — the managed-pub/sub wake (production, no box of our own).
+//
+// Plain-ESM twin of src/lib/agentmail/wake-ably.ts. SAME (ownerId, onWake) ->
+// { close() } contract as the two transports above, so the CLI/TUI handlers are
+// unchanged. The Ably SDK holds ONE socket to Ably's managed service and pushes
+// each wake down it (no polling). For the CLI/dev path (x-neagen-owner header,
+// no Better Auth session) the raw ABLY_API_KEY is fine; a deployed/browser
+// client uses token auth via /api/ably-token instead.
+
+function wakeChannelName(ownerId) {
+  return `wake:${ownerId}`;
+}
+
+export async function subscribeInboxWakeAbly(ownerId, onWake, { key, authUrl, host, bearerToken } = {}) {
+  const { Realtime } = await import("ably");
+  const apiKey = key || process.env.ABLY_API_KEY;
+  const tokenUrl = host && bearerToken ? `${host.replace(/\/$/, "")}/api/ably-token` : undefined;
+  if (!tokenUrl && !authUrl && !apiKey) {
+    throw new Error("Ably wake: set ABLY_API_KEY, pass authUrl, or pass host + bearerToken.");
+  }
+
+  /** @type {import("ably").ClientOptions} */
+  let clientOptions;
+  if (tokenUrl) {
+    clientOptions = {
+      clientId: ownerId,
+      authCallback: (_tokenParams, callback) => {
+        fetch(tokenUrl, { headers: { authorization: `Bearer ${bearerToken}` } })
+          .then(async (res) => {
+            if (!res.ok) throw new Error(`ably-token ${res.status}`);
+            return res.json();
+          })
+          .then((tokenRequest) => callback(null, tokenRequest))
+          .catch((err) => callback(err?.message ?? String(err), null));
+      },
+    };
+  } else if (authUrl) {
+    clientOptions = { authUrl, clientId: ownerId };
+  } else {
+    clientOptions = { key: apiKey, clientId: ownerId };
+  }
+  const client = new Realtime(clientOptions);
+  const channel = client.channels.get(wakeChannelName(ownerId));
+
+  const listener = (msg) => {
+    try {
+      const r = onWake(msg.data);
+      if (r && typeof r.then === "function") r.catch(() => {});
+    } catch {
+      // a handler error must not kill the subscription
+    }
+  };
+  // Don't await subscribe: it rejects on a bad key and stays pending (hangs) if
+  // Ably is unreachable. The listener registers synchronously; the SDK attaches +
+  // reconnects in the background (event-driven, not polling).
+  void channel.subscribe("wake", listener).catch(() => {});
+
+  // Resolve once connected, but never hang if Ably is unreachable (the SDK
+  // reconnects on its own — no polling).
+  await Promise.race([
+    client.connection.once("connected").then(() => {}),
+    new Promise((resolve) => setTimeout(resolve, 1500)),
+  ]);
+
+  return {
+    async close() {
+      channel.unsubscribe("wake", listener);
+      client.close();
+    },
+  };
+}
+
+/**
+ * Pick the wake transport by env.
+ *   - NEAGEN_WAKE_TRANSPORT wins when set: "fs" → fs.watch (pure-local, needs a
+ *     shared filesystem), "ws" → our held WebSocket to the eve wake channel,
+ *     "ably" → Ably managed pub/sub.
+ *   - Otherwise, if ABLY_API_KEY is set → Ably (the production default: no
+ *     always-on box of our own, Ably holds the socket).
+ *   - Otherwise → the held WebSocket.
+ * Same (ownerId, onWake) -> { close() } contract for every transport, so callers
+ * don't branch.
+ */
+export async function subscribeInboxWakeAuto(ownerId, onWake, options = {}) {
+  const transport = process.env.NEAGEN_WAKE_TRANSPORT;
+  if (transport === "fs") return subscribeInboxWake(ownerId, onWake, options);
+  if (transport === "ws") return subscribeInboxWakeWS(ownerId, onWake, options);
+  if (transport === "ably") return subscribeInboxWakeAbly(ownerId, onWake, options);
+  if (process.env.ABLY_API_KEY) return subscribeInboxWakeAbly(ownerId, onWake, options);
+  return subscribeInboxWakeWS(ownerId, onWake, options);
+}
+
+// CLI mode: `node cli/lib/wake.mjs <ownerId>` — subscribe and print one
+// `WOKE <json>` line per wake event (used by the cross-process wake check).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const ownerId = process.argv[2];
+  if (!ownerId) {
+    console.error("usage: node cli/lib/wake.mjs <ownerId>");
+    process.exit(2);
+  }
+  const sub = await subscribeInboxWake(ownerId, (ev) => {
+    process.stdout.write(`WOKE ${JSON.stringify(ev)}\n`);
+  });
+  process.stdout.write("READY\n");
+  const stop = async () => {
+    await sub.close();
+    process.exit(0);
+  };
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+}

package/neagen.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// neagen — your personal networking agent, in the terminal.
+//
+// `neagen`            open the TUI (logs you in on first run)
+// `neagen login`      log in / refresh your session, then exit
+// `neagen logout`     forget the saved session on this machine
+// `neagen doctor`     check connectivity + login status (no terminal UI needed)
+// `neagen --version`  print the version
+//
+// The CLI is a remote client for a deployed Neagen (https://neagen.xyz by
+// default; set NEAGEN_HOST to point elsewhere). Login is the OAuth 2.0 Device
+// Authorization Grant (RFC 8628): you approve with your passkey in the browser.
+// It can only sign in to an EXISTING account — create yours on the web first.
+
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const pkg = require("./package.json");
+
+function parseArgs(argv) {
+  let profile = process.env.NEAGEN_PROFILE?.trim() || undefined;
+  let command;
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--profile" && argv[i + 1]) {
+      profile = argv[++i].trim() || undefined;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") return { command: "help", profile };
+    if (arg === "--version" || arg === "-v") return { command: "version", profile };
+    if (!arg.startsWith("-") && !command) {
+      command = arg;
+      continue;
+    }
+    console.error(`unknown argument: ${arg}  (try: neagen --help)\n`);
+    process.exit(1);
+  }
+  return { command: command ?? "tui", profile };
+}
+
+function printHelp() {
+  process.stdout.write(
+    `neagen ${pkg.version} — your personal networking agent\n\n` +
+      `Usage:\n` +
+      `  neagen [--profile NAME]     Open the agent (logs you in on first run)\n` +
+      `  neagen login                Log in / refresh your session\n` +
+      `  neagen logout               Forget the saved session on this machine\n` +
+      `  neagen doctor               Check connectivity + login status\n` +
+      `  neagen --version            Print the version\n` +
+      `  neagen --help               Show this help\n\n` +
+      `Environment:\n` +
+      `  NEAGEN_HOST                 Server to connect to (default https://neagen.xyz)\n` +
+      `  NEAGEN_PROFILE              Named credential slot (default: the main one)\n\n` +
+      `First time? Create your account at https://neagen.xyz, then run \`neagen\`.\n`,
+  );
+}
+
+async function runTui(profile) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error(
+      "neagen needs an interactive terminal. Try `neagen doctor` to check your setup.\n",
+    );
+    process.exit(1);
+  }
+  if (profile) process.env.NEAGEN_PROFILE = profile;
+  await import("./lib/tui.mjs");
+}
+
+async function runLogin(profile) {
+  const { resolveHost, assertTransportSafe, loadToken, clearCreds } = await import("./lib/creds.mjs");
+  const { resolveIdentity } = await import("./lib/api.mjs");
+  const { runDeviceGrantLogin } = await import("./lib/device-login.mjs");
+  const host = resolveHost();
+  assertTransportSafe(host);
+
+  const existing = loadToken(profile);
+  if (existing) {
+    const me = await resolveIdentity(host, existing).catch(() => null);
+    if (me) {
+      process.stdout.write(`Already logged in to ${host} as ${me.displayName}.\n`);
+      return;
+    }
+    clearCreds(profile);
+  }
+
+  const token = await runDeviceGrantLogin({ host, profile });
+  const me = await resolveIdentity(host, token).catch(() => null);
+  if (!me) {
+    clearCreds(profile);
+    console.error("Session could not be verified after login.\n");
+    process.exit(1);
+  }
+  process.stdout.write(`Logged in to ${host} as ${me.displayName}.\n`);
+}
+
+async function runLogout(profile) {
+  const { clearCreds, credPath } = await import("./lib/creds.mjs");
+  clearCreds(profile);
+  process.stdout.write(`Logged out. Removed ${credPath(profile)}.\n`);
+}
+
+async function runDoctor(profile) {
+  const { resolveHost, assertTransportSafe, loadToken } = await import("./lib/creds.mjs");
+  const { probeHost, resolveIdentity } = await import("./lib/api.mjs");
+  const host = resolveHost();
+  process.stdout.write(`neagen ${pkg.version}\n`);
+  process.stdout.write(`host:   ${host}\n`);
+  try {
+    assertTransportSafe(host);
+  } catch (e) {
+    process.stdout.write(`host:   UNSAFE — ${e.message.split("\n")[0]}\n`);
+    process.exit(2);
+  }
+
+  let reachable = false;
+  try {
+    await probeHost(host);
+    reachable = true;
+    process.stdout.write(`server: reachable\n`);
+  } catch (e) {
+    process.stdout.write(`server: UNREACHABLE (${e.message})\n`);
+  }
+
+  const token = loadToken(profile);
+  if (!token) {
+    process.stdout.write(`login:  not logged in — run \`neagen login\`\n`);
+    process.exit(reachable ? 0 : 2);
+  }
+  if (!reachable) {
+    process.stdout.write(`login:  a session is saved, but the server is unreachable\n`);
+    process.exit(2);
+  }
+  try {
+    const me = await resolveIdentity(host, token);
+    if (me) process.stdout.write(`login:  signed in as ${me.displayName}\n`);
+    else process.stdout.write(`login:  saved session is invalid — run \`neagen login\`\n`);
+    process.exit(0);
+  } catch (e) {
+    process.stdout.write(`login:  could not verify session (${e.message})\n`);
+    process.exit(2);
+  }
+}
+
+const { command, profile } = parseArgs(process.argv);
+
+try {
+  switch (command) {
+    case "help":
+      printHelp();
+      break;
+    case "version":
+      process.stdout.write(`${pkg.version}\n`);
+      break;
+    case "login":
+      await runLogin(profile);
+      break;
+    case "logout":
+      await runLogout(profile);
+      break;
+    case "doctor":
+      await runDoctor(profile);
+      break;
+    case "tui":
+      await runTui(profile);
+      break;
+    default:
+      console.error(`unknown command: ${command}  (try: neagen --help)\n`);
+      process.exit(1);
+  }
+} catch (error) {
+  console.error(`\n  ${error?.message ?? error}\n`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "neagen",
+  "version": "0.1.0",
+  "description": "Your personal networking agent, in the terminal. Chat, agent-mail, and files against your Neagen — passkey login, no passwords.",
+  "type": "module",
+  "bin": {
+    "neagen": "neagen.mjs"
+  },
+  "files": [
+    "neagen.mjs",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "ably": "^2.23.0",
+    "eve": "0.14.0"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://neagen.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Remedy92/neagen.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Remedy92/neagen/issues"
+  },
+  "keywords": [
+    "neagen",
+    "networking",
+    "agent",
+    "cli",
+    "tui",
+    "passkey"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}