meksus 0.3.0

package/README.md

@@ -0,0 +1,67 @@
+# meksus
+
+The command-line companion to **[M.E.K.S.U.S.](https://meksus.pages.dev)**: see what your AI coding agents and builds are doing, live, and get a Discord alert when something fails or needs you.
+
+> **Private preview.** Anyone can install the CLI. Reporting to M.E.K.S.U.S. needs a signed-in account with access. Right now that means Lore Inc. members and invited accounts; paid plans come later.
+
+## Install
+
+```sh
+npm install -g meksus
+meksus help
+```
+
+You need Node.js 20 or later. On Windows, run these in PowerShell or Windows Terminal.
+
+## Connect a repository (about 2 minutes)
+
+```sh
+meksus login                          # once per computer: opens GitHub in your browser
+cd path/to/your-repo
+meksus project list                   # your organisations, Personal, and their projects
+meksus project use <owner/project>    # writes .meksus at the repository root
+git add .meksus && git commit -m "Add .meksus (M.E.K.S.U.S. project)" && git push
+```
+
+The project's exact `<owner/project>` name is shown on its page in the dashboard, under **Project settings → Connect this project's repository**. `.meksus` holds identifiers only (project name and id), never a key, so it's safe to commit.
+
+## Watch Claude Code and your builds
+
+```sh
+meksus hooks install                          # in the repo: adds Claude Code hooks to .claude/settings.local.json
+meksus task-lines steps                       # optional: show the step Claude is on, in one line
+meksus watch --label "build" -- npm run build # any command; a failure opens an incident and alerts Discord
+```
+
+Start a new Claude Code session after installing the hooks. It then appears on the dashboard's **Agents** page: working, waiting for you, finished, or stuck.
+
+## Check
+
+```sh
+meksus status    # who you're signed in as, whether you have access, and this repo's project
+```
+
+## What is sent
+
+**Status only:** session state, timings, tool-call counts and token totals, plus a command's exit code for `meksus watch`. Code, prompts and command output never leave your machine.
+
+With `meksus task-lines` turned on (it's off by default), two more things are sent:
+- the title of the step Claude is working on;
+- the paths of files it's editing or reading, relative to the repository (never contents).
+
+The server scrubs anything that looks like a secret.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `meksus login` / `logout` | Sign in with GitHub, or sign out |
+| `meksus status` | Account, access, and this repo's project |
+| `meksus project list` | Your organisations, Personal, and their projects |
+| `meksus project create <name> [--in <parent>] [--use]` | Create a project (owners and admins) |
+| `meksus project use <owner/project>` | Write this repo's `.meksus` |
+| `meksus hooks install` / `uninstall` | Watch Claude Code in this repo |
+| `meksus task-lines off \| steps \| prompt` | Opt-in one-line "working on" |
+| `meksus watch [--label <name>] -- <cmd>` | Run a command and report how it ends |
+
+© Lore Inc. All rights reserved.

package/bin/meksus.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// M.E.K.S.U.S. CLI. Zero dependencies; Node ≥ 20.
+import { hasAccess, PREVIEW_TEXT, requireAccess } from "../src/access.mjs";
+import { login, logout } from "../src/auth.mjs";
+import { install, runHook, uninstall } from "../src/hooks.mjs";
+import { apiBase, dir, readConfig } from "../src/config.mjs";
+import { projectCommand, readProjectFile } from "../src/project.mjs";
+import { flush } from "../src/spool.mjs";
+import { taskLinesCommand } from "../src/tasks.mjs";
+import { VERSION } from "../src/version.mjs";
+import { watch } from "../src/watch.mjs";
+
+const HELP = `M.E.K.S.U.S. CLI ${VERSION}
+
+  meksus login [--no-browser]                     Sign in with GitHub (your account, not this machine)
+  meksus logout                                   End this sign-in
+  meksus status                                   Who you are, and which project this repo reports to
+  meksus project list                             Your organisations, Personal, and their projects
+  meksus project create <name> [--in <parent>] [--slug <slug>] [--use]
+  meksus project use <owner/project>              Write this repo's .meksus file (commit it)
+  meksus hooks install | uninstall                Watch Claude Code in the current repository
+  meksus task-lines [off | steps | prompt]        Show what Claude is working on, in one line (opt-in)
+  meksus watch [--label <name>] -- <cmd> …        Run a command and report its status; a failure opens an incident
+
+Status only: code, prompts and command output never leave your machine. With task-lines on, the title
+of the step Claude is on (and, in "prompt" mode, each prompt's first line) is sent as well.
+Access: M.E.K.S.U.S. is in private preview (Lore Inc. members and invited accounts). Anyone can install
+the CLI; reporting needs a signed-in account with access.
+Config: ${dir()} (override with MEKSUS_CONFIG_DIR). API: MEKSUS_API.`;
+
+const [command, ...rest] = process.argv.slice(2);
+const flag = (name) => rest.includes(name);
+
+let code = 0;
+switch (command) {
+  case "login": code = await login({ noBrowser: flag("--no-browser") }); break;
+  case "logout": code = await logout(); break;
+  case "status": code = await status(); break;
+  case "project": case "projects": code = (await requireAccess()) ? await projectCommand(rest) : 1; break;
+  case "hooks":
+    if (rest[0] === "install") code = (await requireAccess()) ? install() : 1;
+    else if (rest[0] === "uninstall") code = uninstall();
+    else { console.error("Usage: meksus hooks install | uninstall"); code = 2; }
+    break;
+  case "hook": code = await runHook(); break; // called by Claude Code, silent
+  case "task-lines": code = taskLinesCommand(rest); break;
+  case "flush": await flush(); break; // internal, detached
+  case "watch": code = await watch(rest); break;
+  case "--version": case "-v": case "version": console.log(VERSION); break;
+  default: console.log(HELP); code = command && command !== "help" && command !== "--help" ? 2 : 0;
+}
+process.exitCode = code;
+// login/logout are one-shot: exit as soon as the session is saved, whatever a socket or timer is still doing.
+if (command === "login" || command === "logout") process.exit(code);
+
+async function status() {
+  const c = readConfig();
+  const project = readProjectFile();
+  if (!c?.session) console.log("Not signed in. Run `meksus login`.");
+  else {
+    console.log(`Signed in as ${c.user?.name ?? "?"}${c.user?.email ? ` (${c.user.email})` : ""} since ${c.signed_in_at}`);
+    const ok = await hasAccess({ fresh: true });
+    console.log(ok === true ? "Access: yes" : ok === false ? `Access: no. ${PREVIEW_TEXT}` : "Access: couldn't check right now (offline?)");
+  }
+  console.log(project ? `This repo reports to ${project.name ?? project.id}  (${project.file})` : "This repo has no .meksus file: nothing here is reported. `meksus project use <owner/project>` adds one.");
+  console.log(`API ${apiBase(c)}`);
+  return c?.session ? 0 : 1;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "meksus",
+  "version": "0.3.0",
+  "description": "M.E.K.S.U.S. CLI: see what your AI coding agents (Claude Code) and builds are doing, live, and get Discord alerts when they fail or need you. Status only: code, prompts and output never leave your machine.",
+  "keywords": [
+    "meksus",
+    "claude-code",
+    "ai-agents",
+    "monitoring",
+    "discord",
+    "alerts",
+    "cli",
+    "devops"
+  ],
+  "homepage": "https://meksus.pages.dev",
+  "author": "Lore Inc.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "meksus": "bin/meksus.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/access.mjs

@@ -0,0 +1,43 @@
+// Who may use M.E.K.S.U.S. right now (access gate, M5 slice C): the database decides, per signed-in
+// user (Lore Inc. members, the comp list, and later paid plans). The CLI only asks the same yes/no
+// question the dashboard asks (public.my_access) so it can explain itself instead of failing quietly.
+// Every server path enforces the gate anyway; this is for clear messages, not for security.
+import { getAccessToken } from "./auth.mjs";
+import { readConfig, writeConfig } from "./config.mjs";
+
+const CACHE_MS = 60 * 60_000; // re-asked at most hourly (hooks run constantly; this must stay cheap)
+
+export const PREVIEW_TEXT = "M.E.K.S.U.S. is in private preview. Your account doesn't have access yet: it's open to Lore Inc. members and invited accounts (paid plans come later). See https://meksus.pages.dev";
+
+/** true / false, or null when it can't be determined (offline, signed out). */
+export async function hasAccess({ fresh = false, config = readConfig() } = {}) {
+  if (!config?.session) return null;
+  const c = config.access;
+  if (!fresh && c && Date.now() - c.at < CACHE_MS && c.user === config.user?.id) return c.ok;
+  const token = await getAccessToken(config);
+  if (!token) return null;
+  try {
+    const res = await fetch(`${config.supabase_url.replace(/\/$/, "")}/rest/v1/rpc/my_access`, {
+      method: "POST",
+      headers: { apikey: config.supabase_publishable_key, Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: "{}",
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!res.ok) { await res.body?.cancel(); return null; }
+    const ok = (await res.json()) === true;
+    writeConfig({ ...(readConfig() ?? config), access: { ok, at: Date.now(), user: config.user?.id } });
+    return ok;
+  } catch {
+    return null;
+  }
+}
+
+/** For commands that need an account with access: prints why not, returns false. */
+export async function requireAccess() {
+  const config = readConfig();
+  if (!config?.session) { console.error("✖ Not signed in. Run `meksus login` first."); return false; }
+  const ok = await hasAccess({ config });
+  if (ok === false) { console.error(`✖ ${PREVIEW_TEXT}`); return false; }
+  if (ok === null) console.error("! Couldn't confirm access right now (offline?). Continuing; the server checks again.");
+  return true;
+}

package/src/api.mjs

@@ -0,0 +1,33 @@
+// Transport: one batch of agent session rows for one project, sent as the signed-in user
+// (Authorization: Bearer <access token>, refreshed when needed) with the project from .meksus.
+import { getAccessToken } from "./auth.mjs";
+import { apiBase, readConfig, writeConfig } from "./config.mjs";
+import { VERSION } from "./version.mjs";
+
+/** Sends one batch. Returns the HTTP status (0 on network failure or when signed out). */
+export async function sendAgentEvents(events, { project, config = readConfig(), timeoutMs = 8000 } = {}) {
+  if (!project || !events.length) return 0;
+  const token = await getAccessToken(config);
+  if (!token) return 0;
+  try {
+    const res = await fetch(`${apiBase(config)}/v1/agent-events`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": `meksus-cli/${VERSION}`,
+        Authorization: `Bearer ${token}`,
+        "X-Meksus-Project": project,
+      },
+      body: JSON.stringify({ events }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    // 403 no_access: remember it, so `meksus status` and commands explain it (re-checked hourly).
+    if (res.status === 403) {
+      const body = await res.json().catch(() => null);
+      if (body?.error === "no_access") writeConfig({ ...(readConfig() ?? config), access: { ok: false, at: Date.now(), user: config.user?.id } });
+    } else await res.body?.cancel();
+    return res.status;
+  } catch {
+    return 0;
+  }
+}

package/src/auth.mjs

@@ -0,0 +1,149 @@
+// `meksus login` / `meksus logout`, and a fresh access token for every send.
+//
+// Sign-in is Supabase Auth with GitHub, using PKCE (the same as the web app), so no token is ever
+// typed, pasted or shown:
+//   1. ask the ingest Worker where Supabase lives (/v1/cli/config: public values only)
+//   2. listen on http://127.0.0.1:<random port> for one callback
+//   3. open <supabase>/auth/v1/authorize?provider=github&code_challenge=…  The browser comes back to
+//      https://<app>/cli-callback, a static page that forwards ?code= to the local listener. The code is
+//      useless without this process's verifier, which never leaves it.
+//   4. exchange code + verifier for a session; keep it in config.json (0600)
+// Access tokens last an hour; getAccessToken() refreshes them (rotating refresh token) when needed.
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { apiBase, paths, readConfig, writeConfig } from "./config.mjs";
+import { VERSION } from "./version.mjs";
+
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+const b64url = (buf) => buf.toString("base64url");
+
+export async function discover(api = apiBase()) {
+  const res = await fetch(`${api}/v1/cli/config`, { headers: { "User-Agent": `meksus-cli/${VERSION}` }, signal: AbortSignal.timeout(8000) });
+  if (!res.ok) throw new Error(`M.E.K.S.U.S. at ${api} answered HTTP ${res.status}`);
+  return res.json();
+}
+
+export async function login({ noBrowser = false } = {}) {
+  // Loaded here, not at the top: access.mjs imports getAccessToken from this module.
+  const { hasAccess, PREVIEW_TEXT } = await import("./access.mjs");
+  const api = apiBase();
+  let cfg;
+  try { cfg = await discover(api); } catch (err) { console.error(`✖ Could not reach M.E.K.S.U.S. (${err.message}).`); return 1; }
+
+  const verifier = b64url(randomBytes(32));
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  const state = b64url(randomBytes(16));
+
+  let finish;
+  const done = new Promise((resolve) => { finish = resolve; });
+  const server = createServer((req, res) => {
+    const url = new URL(req.url, "http://127.0.0.1");
+    if (url.pathname !== "/callback") { res.writeHead(404).end(); return; }
+    const refused = url.searchParams.get("state") === state && url.searchParams.get("error");
+    const ok = url.searchParams.get("state") === state && url.searchParams.get("code");
+    if (refused) {
+      res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store", Connection: "close" }).end("ok");
+      finish({ error: url.searchParams.get("error") });
+      return;
+    }
+    // Connection: close, so the browser doesn't hold a keep-alive socket that keeps this process running.
+    res.writeHead(ok ? 200 : 400, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store", Connection: "close" });
+    res.end(`<!doctype html><meta charset="utf-8"><title>M.E.K.S.U.S. CLI</title><body style="font:16px system-ui;background:#08090D;color:#e6e8ec;display:grid;place-items:center;height:90vh"><p>${ok ? "✔ Signed in. You can close this tab and return to your terminal." : "✖ This sign-in link doesn't match the one your terminal started. Run <code>meksus login</code> again."}</p>`);
+    if (ok) finish(url.searchParams.get("code"));
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const port = server.address().port;
+
+  const redirect = `${cfg.app_url.replace(/\/$/, "")}/cli-callback?port=${port}&state=${state}`;
+  const authorize = `${cfg.supabase_url.replace(/\/$/, "")}/auth/v1/authorize?${new URLSearchParams({
+    provider: "github", redirect_to: redirect, code_challenge: challenge, code_challenge_method: "s256",
+  })}`;
+
+  console.log("\n  Sign in to M.E.K.S.U.S. with GitHub\n");
+  console.log(`  Open: ${authorize}\n`);
+  if (!noBrowser) openBrowser(authorize);
+  process.stdout.write("  Waiting for the browser");
+  const tick = setInterval(() => process.stdout.write("."), 2000);
+  let timer;
+  const code = await Promise.race([done, new Promise((r) => { timer = setTimeout(() => r(null), LOGIN_TIMEOUT_MS); })]);
+  // Release everything that would keep Node alive: the dots, the 5-minute timer, and the listener with any
+  // socket the browser left open. bin/meksus.mjs also exits explicitly once login returns.
+  clearInterval(tick);
+  clearTimeout(timer);
+  server.close();
+  server.closeAllConnections();
+  if (!code) { console.log("\n\n  ✖ Timed out. Run `meksus login` again."); return 1; }
+  if (code.error) {
+    console.log(code.error === "private_preview" ? `\n\n  ✖ ${PREVIEW_TEXT}\n` : `\n\n  ✖ Sign-in didn't complete (${code.error}). Run \`meksus login\` again.\n`);
+    return 1;
+  }
+
+  const res = await fetch(`${cfg.supabase_url.replace(/\/$/, "")}/auth/v1/token?grant_type=pkce`, {
+    method: "POST",
+    headers: { apikey: cfg.supabase_publishable_key, "Content-Type": "application/json" },
+    body: JSON.stringify({ auth_code: code, code_verifier: verifier }),
+    signal: AbortSignal.timeout(10_000),
+  });
+  const s = await res.json().catch(() => null);
+  if (!res.ok || !s?.access_token) { console.log(`\n\n  ✖ Sign-in failed (${s?.error_description ?? s?.msg ?? `HTTP ${res.status}`}).`); return 1; }
+
+  const user = { id: s.user.id, email: s.user.email ?? null, name: s.user.user_metadata?.full_name || s.user.user_metadata?.name || s.user.user_metadata?.user_name || s.user.email };
+  // Keep the machine's preferences (task lines) across sign-ins; only the session parts are replaced.
+  const prefs = { task_lines: readConfig()?.task_lines };
+  writeConfig({ ...prefs, api, supabase_url: cfg.supabase_url, supabase_publishable_key: cfg.supabase_publishable_key, app_url: cfg.app_url, user, session: toSession(s), signed_in_at: new Date().toISOString() });
+  // Signed in is not the same as allowed in: without access, say so and don't keep the session.
+  if ((await hasAccess({ fresh: true })) === false) {
+    await logout({ quiet: true });
+    console.log(`\n\n  ✖ Signed in as ${user.name}, but ${PREVIEW_TEXT.replace(/^M\.E\.K\.S\.U\.S\. is/, "M.E.K.S.U.S. is")}\n    You've been signed out again.\n`);
+    return 1;
+  }
+  console.log(`\n\n  ✔ Signed in as ${user.name}${user.email ? ` (${user.email})` : ""}.`);
+  console.log(`    Session saved to ${paths().config} (readable by you only). \`meksus logout\` ends it.`);
+  console.log("    Next: `meksus project list`, then `meksus project use <owner/project>` in a repo.\n");
+  return 0;
+}
+
+export async function logout({ quiet = false } = {}) {
+  const c = readConfig();
+  if (!c?.session) { if (!quiet) console.log("Not signed in."); return 0; }
+  // End this session on the server too (scope=local: other sign-ins, like the browser, stay).
+  try {
+    const token = await getAccessToken(c);
+    if (token) {
+      await fetch(`${c.supabase_url}/auth/v1/logout?scope=local`, { method: "POST", headers: { apikey: c.supabase_publishable_key, Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(8000) });
+    }
+  } catch { /* forget locally anyway */ }
+  writeConfig({ api: c.api, task_lines: c.task_lines });
+  if (!quiet) console.log("Signed out. Hooks and `meksus watch` stop reporting until you sign in again.");
+  return 0;
+}
+
+const toSession = (s) => ({ access_token: s.access_token, refresh_token: s.refresh_token, expires_at: s.expires_at ?? Math.floor(Date.now() / 1000) + (s.expires_in ?? 3600) });
+
+/** A valid access token, refreshed if it expires within a minute. Null if signed out or refresh failed. */
+export async function getAccessToken(config = readConfig()) {
+  const s = config?.session;
+  if (!s?.refresh_token) return null;
+  if (s.access_token && s.expires_at - 60 > Date.now() / 1000) return s.access_token;
+  try {
+    const res = await fetch(`${config.supabase_url}/auth/v1/token?grant_type=refresh_token`, {
+      method: "POST",
+      headers: { apikey: config.supabase_publishable_key, "Content-Type": "application/json" },
+      body: JSON.stringify({ refresh_token: s.refresh_token }),
+      signal: AbortSignal.timeout(8000),
+    });
+    const next = await res.json().catch(() => null);
+    if (!res.ok || !next?.access_token) return null;
+    // Re-read before writing: another meksus process may have refreshed meanwhile.
+    writeConfig({ ...(readConfig() ?? config), session: toSession(next) });
+    return next.access_token;
+  } catch {
+    return null;
+  }
+}
+
+export function openBrowser(url) {
+  const [cmd, args] = process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try { spawn(cmd, args, { stdio: "ignore", detached: true, windowsHide: true }).unref(); } catch { /* the URL is printed anyway */ }
+}

package/src/config.mjs

@@ -0,0 +1,42 @@
+// Local state for the CLI. Everything lives in one directory (default ~/.meksus, override with
+// MEKSUS_CONFIG_DIR): config.json (your sign-in session, mode 0600), the event spool, and flush markers.
+// Nothing about this machine is registered with M.E.K.S.U.S. (PRJ-10): the session is yours, like
+// `gh auth login`, and `meksus logout` ends it.
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// The one account-specific default in the CLI (docs/MIGRATION.md): where the ingest Worker lives.
+// Override with MEKSUS_API for another deployment. Everything else is discovered from /v1/cli/config.
+export const DEFAULT_API = "https://meksus-ingest.shirosakura72.workers.dev";
+
+export const dir = () => process.env.MEKSUS_CONFIG_DIR || join(homedir(), ".meksus");
+export const paths = () => ({
+  config: join(dir(), "config.json"),
+  spool: join(dir(), "spool.jsonl"),
+  lock: join(dir(), "flush.lock"),
+  lastFlush: join(dir(), "last-flush"),
+});
+
+export function ensureDir() {
+  mkdirSync(dir(), { recursive: true, mode: 0o700 });
+}
+
+export function readConfig() {
+  try { return JSON.parse(readFileSync(paths().config, "utf8")); } catch { return null; }
+}
+
+export function writeConfig(config) {
+  ensureDir();
+  const tmp = `${paths().config}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(config, null, 2), { mode: 0o600 });
+  renameSync(tmp, paths().config);
+  try { chmodSync(paths().config, 0o600); } catch { /* Windows: ACLs of the user profile apply */ }
+}
+
+export function apiBase(config = readConfig()) {
+  return (process.env.MEKSUS_API || config?.api || DEFAULT_API).replace(/\/$/, "");
+}
+
+export const isSignedIn = (c = readConfig()) => Boolean(c?.session?.refresh_token);
+export const hasConfigDir = () => existsSync(dir());

package/src/hooks.mjs

@@ -0,0 +1,168 @@
+// Claude Code integration.
+//   `meksus hook`            the hook command itself: reads the hook JSON on stdin, records a status
+//                            line, exits 0 and prints NOTHING (some hooks feed stdout back to Claude).
+//   `meksus hooks install`   adds the hook to <repo>/.claude/settings.local.json (personal, gitignored)
+//   `meksus hooks uninstall` removes only our entries
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readProjectFile } from "./project.mjs";
+import { record } from "./spool.mjs";
+import { taskFrom, taskMode } from "./tasks.mjs";
+
+const EVENTS = ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Notification", "Stop", "SessionEnd"];
+const TOOL_EVENTS = new Set(["PreToolUse", "PostToolUse"]);
+const CLI = fileURLToPath(new URL("../bin/meksus.mjs", import.meta.url));
+const MARK = "meksus.mjs\" hook";
+
+export function sessionKey(agent, id) {
+  return createHash("sha256").update(`${agent}:${id}`).digest("hex").slice(0, 32); // never the raw id
+}
+
+/** Maps one Claude Code hook payload to a status line (or null to ignore). Exported for tests. */
+export function toStatus(input, now = new Date()) {
+  const name = input?.hook_event_name;
+  if (!name || !input.session_id) return null;
+  // PRJ-10/13: status belongs to the project named by the repo's .meksus file; no file → not reported.
+  const project = typeof input.cwd === "string" ? readProjectFile(input.cwd)?.id : null;
+  if (!project) return null;
+  const e = {
+    project,
+    session: sessionKey("claude-code", input.session_id),
+    agent: "claude-code",
+    label: repoLabel(input.cwd),
+    at: now.toISOString(),
+    transcript: typeof input.transcript_path === "string" ? input.transcript_path : null,
+  };
+  switch (name) {
+    case "SessionStart": return { ...e, state: "idle", started_at: e.at };
+    case "UserPromptSubmit": return { ...e, state: "working" };
+    case "PreToolUse": return { ...e, state: "working", tool_call: true };
+    case "PostToolUse": return { ...e, state: "working", tool_failure: toolFailed(input.tool_response) };
+    case "PostToolUseFailure": return { ...e, state: "working", tool_failure: true };
+    case "Notification": return { ...e, state: "waiting" };
+    case "Stop": return { ...e, state: "finished" };
+    case "SessionEnd": return { ...e, state: "finished", ended: true };
+    default: return null;
+  }
+}
+
+function toolFailed(r) {
+  if (!r || typeof r !== "object") return false;
+  return r.is_error === true || r.success === false || (typeof r.error === "string" && r.error.length > 0);
+}
+
+function repoRoot(cwd) {
+  let d = resolve(cwd);
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(join(d, ".git"))) return d;
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return resolve(cwd);
+}
+
+const FILE_TOOLS = { Edit: "edit", MultiEdit: "edit", Write: "edit", NotebookEdit: "edit", Read: "read" };
+
+/** Opt-in with task lines: the file a tool is about to touch, as a path inside the repo (a file outside
+ *  the repo is reduced to its name). Never the contents, never an absolute path. Exported for tests. */
+export function fileFrom(input, mode) {
+  if (mode === "off" || input?.hook_event_name !== "PreToolUse") return null;
+  const action = FILE_TOOLS[input.tool_name];
+  const target = input.tool_input?.file_path ?? input.tool_input?.notebook_path;
+  if (!action || typeof target !== "string" || !target || typeof input.cwd !== "string") return null;
+  const abs = resolve(input.cwd, target);
+  const rel = relative(repoRoot(input.cwd), abs);
+  const path = !rel || rel.startsWith("..") || isAbsolute(rel) ? basename(abs) : rel.split("\\").join("/");
+  return { file_path: path.slice(0, 160), file_action: action };
+}
+
+/** "owner/repo" from the repository's GitHub remote (origin first), or null. Exported for tests. */
+export function githubName(gitConfig) {
+  const remotes = [...gitConfig.matchAll(/\[remote "([^"]+)"\][^[]*?\burl\s*=\s*(\S+)/g)].map((m) => ({ name: m[1], url: m[2] }));
+  remotes.sort((a, b) => (a.name === "origin" ? -1 : b.name === "origin" ? 1 : 0));
+  for (const { url } of remotes) {
+    const m = /github\.com[:/]([A-Za-z0-9-]{1,39})\/([A-Za-z0-9._-]{1,100}?)(?:\.git)?\/?$/.exec(url);
+    if (m) return `${m[1]}/${m[2]}`;
+  }
+  return null;
+}
+
+/** Label = "owner/repo" as GitHub names it (from the remote), else the repository's folder name; never a path. */
+export function repoLabel(cwd) {
+  if (typeof cwd !== "string" || !cwd) return null;
+  const root = repoRoot(cwd);
+  try {
+    const named = githubName(readFileSync(join(root, ".git", "config"), "utf8"));
+    if (named) return named.slice(0, 80);
+  } catch { /* no git config (worktree file, not a repo): fall back to the folder */ }
+  return basename(root).slice(0, 80);
+}
+
+export async function runHook() {
+  try {
+    const chunks = [];
+    for await (const c of process.stdin) chunks.push(c);
+    const input = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    const status = toStatus(input);
+    if (status) {
+      // Opt-in one-line "working on" from the agent's own step list (`meksus task-lines`).
+      const mode = taskMode();
+      const task = taskFrom(input, status.session, mode);
+      if (task) Object.assign(status, task);
+      const file = fileFrom(input, mode);
+      if (file) Object.assign(status, file);
+      record(status);
+    }
+  } catch { /* a monitoring hook must never break the agent */ }
+  return 0;
+}
+
+// ── install / uninstall ─────────────────────────────────────────
+function settingsPath(cwd) {
+  let d = resolve(cwd);
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(join(d, ".git"))) break;
+    const up = dirname(d);
+    if (up === d) { d = resolve(cwd); break; }
+    d = up;
+  }
+  return join(d, ".claude", "settings.local.json");
+}
+
+export function install(cwd = process.cwd()) {
+  const file = settingsPath(cwd);
+  const settings = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+  settings.hooks ??= {};
+  const command = `node "${CLI}" hook`;
+  for (const event of EVENTS) {
+    const groups = (settings.hooks[event] ??= []);
+    const clean = groups.map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !String(h.command).includes(MARK)) })).filter((g) => g.hooks.length);
+    clean.push({ ...(TOOL_EVENTS.has(event) ? { matcher: "*" } : {}), hooks: [{ type: "command", command, timeout: 10 }] });
+    settings.hooks[event] = clean;
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
+  console.log(`✔ Claude Code hooks installed in ${file}`);
+  console.log("  Sent: session state, timings, tool-call counts and token totals. Never code, prompts or output.");
+  console.log("  Optional: `meksus task-lines steps` also shows what Claude is working on (its to-do step, else its current action).");
+  console.log("  Start a new Claude Code session in this repo (or review them with /hooks) to activate.");
+  return 0;
+}
+
+export function uninstall(cwd = process.cwd()) {
+  const file = settingsPath(cwd);
+  if (!existsSync(file)) { console.log("No hooks file here."); return 0; }
+  const settings = JSON.parse(readFileSync(file, "utf8"));
+  for (const event of Object.keys(settings.hooks ?? {})) {
+    settings.hooks[event] = settings.hooks[event]
+      .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !String(h.command).includes(MARK)) }))
+      .filter((g) => g.hooks.length);
+    if (!settings.hooks[event].length) delete settings.hooks[event];
+  }
+  writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
+  console.log(`✔ M.E.K.S.U.S. hooks removed from ${file}`);
+  return 0;
+}

package/src/project.mjs

@@ -0,0 +1,159 @@
+// Projects (PRJ-2, PRJ-12, PRJ-13).
+//   meksus project list                           your parents (Personal, organisations) and their projects
+//   meksus project create <name> [--in <parent>] [--slug <slug>] [--use]
+//   meksus project use <owner/project | id>       write this repo's .meksus file
+//
+// .meksus is committed to the project's repo so teammates, clones and AI agents can see that
+// M.E.K.S.U.S. tracks it. It holds identifiers only, never a key: the file is public to anyone who
+// can read the repo. Agent status from this repo is attributed to that project.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { getAccessToken } from "./auth.mjs";
+import { apiBase, readConfig } from "./config.mjs";
+
+export const PROJECT_FILE = ".meksus";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The repo root (nearest folder with .git), or the folder itself. */
+export function repoRoot(cwd = process.cwd()) {
+  let d = resolve(cwd);
+  for (let i = 0; i < 40; i++) {
+    if (existsSync(join(d, ".git"))) return d;
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return resolve(cwd);
+}
+
+/** The project named by the nearest .meksus file above `cwd`, or null. */
+export function readProjectFile(cwd = process.cwd()) {
+  let d = resolve(cwd);
+  for (let i = 0; i < 40; i++) {
+    const f = join(d, PROJECT_FILE);
+    if (existsSync(f)) {
+      try {
+        const p = JSON.parse(readFileSync(f, "utf8"));
+        return UUID.test(p?.id ?? "") ? { id: p.id.toLowerCase(), name: typeof p.project === "string" ? p.project : null, file: f } : null;
+      } catch { return null; }
+    }
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return null;
+}
+
+async function call(method, path, body) {
+  const config = readConfig();
+  const token = await getAccessToken(config);
+  if (!token) { console.error("✖ Not signed in. Run `meksus login` first."); return null; }
+  const res = await fetch(`${apiBase(config)}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "User-Agent": "meksus-cli/0.2" },
+    body: body ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(10_000),
+  }).catch(() => null);
+  if (!res) { console.error("✖ Could not reach M.E.K.S.U.S."); return null; }
+  const json = await res.json().catch(() => null);
+  if (res.status === 401) { console.error("✖ Your sign-in has expired. Run `meksus login` again."); return null; }
+  return { status: res.status, json };
+}
+
+const ownerOf = (ws) => ws?.github_owner || ws?.name || "?";
+export const fullName = (ws, p) => `${ownerOf(ws)}/${p.slug}`;
+
+async function load() {
+  const r = await call("GET", "/v1/cli/projects");
+  if (!r) return null;
+  if (r.status !== 200) { console.error(`✖ Could not list projects (${r.json?.error ?? `HTTP ${r.status}`}).`); return null; }
+  return r.json;
+}
+
+export async function projectCommand(args) {
+  const [sub, ...rest] = args;
+  const value = (flag) => (rest.includes(flag) ? rest[rest.indexOf(flag) + 1] : undefined);
+  if (sub === "list" || sub === "ls" || !sub) return list();
+  if (sub === "use") return use(rest[0]);
+  if (sub === "create") {
+    const name = rest.filter((a, i) => !a.startsWith("--") && !["--in", "--slug"].includes(rest[i - 1])).join(" ").trim();
+    return create(name, { parent: value("--in"), slug: value("--slug"), use: rest.includes("--use") });
+  }
+  console.error("Usage: meksus project list | create <name> [--in <parent>] [--slug <slug>] [--use] | use <owner/project>");
+  return 2;
+}
+
+async function list() {
+  const data = await load();
+  if (!data) return 1;
+  const here = readProjectFile();
+  for (const ws of data.workspaces) {
+    console.log(`\n  ${ws.name}${ws.github_owner ? ` (${ws.github_owner})` : ""}  ·  ${ws.kind === "personal" ? "Personal" : "Organization"}`);
+    const mine = data.projects.filter((p) => p.workspace_id === ws.id);
+    if (!mine.length) console.log("    (no projects yet)");
+    for (const p of mine) {
+      const mark = here?.id === p.id ? "▶" : " ";
+      console.log(`  ${mark} ${fullName(ws, p).padEnd(34)} ${p.name.padEnd(16)} ${p.discord_guild_name ? `Discord: ${p.discord_guild_name}` : "Discord: not bound"}`);
+      console.log(`      ${p.id}`);
+    }
+  }
+  console.log(here ? `\n  ▶ = this repo (${here.file})\n` : "\n  This repo has no .meksus file. `meksus project use <owner/project>` adds one.\n");
+  return 0;
+}
+
+function find(data, ref) {
+  if (!ref) return null;
+  const r = ref.toLowerCase();
+  for (const p of data.projects) {
+    const ws = data.workspaces.find((w) => w.id === p.workspace_id);
+    if (p.id === r || fullName(ws, p).toLowerCase() === r) return { p, ws };
+  }
+  const bySlug = data.projects.filter((p) => p.slug.toLowerCase() === r || p.name.toLowerCase() === r);
+  return bySlug.length === 1 ? { p: bySlug[0], ws: data.workspaces.find((w) => w.id === bySlug[0].workspace_id) } : null;
+}
+
+export function writeProjectFile(ws, p, root = repoRoot()) {
+  const file = join(root, PROJECT_FILE);
+  const content = {
+    about: "This repository is watched by M.E.K.S.U.S. Identifiers only; never put a key or secret here.",
+    project: fullName(ws, p),
+    id: p.id,
+  };
+  writeFileSync(file, `${JSON.stringify(content, null, 2)}\n`);
+  return file;
+}
+
+async function use(ref) {
+  if (!ref) { console.error("Usage: meksus project use <owner/project | id>"); return 2; }
+  const data = await load();
+  if (!data) return 1;
+  const hit = find(data, ref);
+  if (!hit) { console.error(`✖ No project "${ref}" among yours. \`meksus project list\` shows them.`); return 1; }
+  const file = writeProjectFile(hit.ws, hit.p);
+  console.log(`✔ ${file} now names ${fullName(hit.ws, hit.p)}. Commit it so everyone working in this repo reports to the same project.`);
+  return 0;
+}
+
+async function create(name, { parent, slug, use: andUse }) {
+  if (!name) { console.error("Usage: meksus project create <name> [--in <parent>] [--slug <slug>] [--use]"); return 2; }
+  const data = await load();
+  if (!data) return 1;
+  const p = (parent ?? "").toLowerCase();
+  const ws = parent
+    ? data.workspaces.find((w) => w.id === p || w.name.toLowerCase() === p || (w.github_owner ?? "").toLowerCase() === p)
+    : data.workspaces.find((w) => w.kind === "personal");
+  if (!ws) { console.error(`✖ No parent "${parent}". Yours: ${data.workspaces.map((w) => w.name).join(", ")}.`); return 1; }
+
+  const r = await call("POST", "/v1/cli/projects", { workspace: ws.id, name, slug });
+  if (!r) return 1;
+  if (r.status !== 201) {
+    const why = { not_allowed: "only owners and admins can create projects there", slug_taken: "that name is taken in this parent (try --slug)", bad_slug: "use letters, digits, '.', '-' or '_' for --slug", bad_name: "the name must be 1–60 characters", too_many_projects: "this parent already has 100 projects" };
+    console.error(`✖ Not created: ${why[r.json?.error] ?? r.json?.error ?? `HTTP ${r.status}`}.`);
+    return 1;
+  }
+  const project = r.json.project;
+  console.log(`✔ Created ${fullName(ws, project)} (${project.id}).`);
+  console.log("  Its Discord server and signing key are on the project page in the dashboard.");
+  if (andUse) console.log(`✔ ${writeProjectFile(ws, project)} written. Commit it.`);
+  return 0;
+}

package/src/spool.mjs

@@ -0,0 +1,110 @@
+// Local event spool + batched flush (G-1: never one network call per hook event).
+//   record(): append one status line to spool.jsonl (atomic small append) and, if due, start a
+//             detached `meksus flush` so the caller (a Claude Code hook) returns immediately.
+//   flush():  take a lock, move the spool aside, aggregate ONE row per session, send ONE request per
+//             project (usually one), then drop the batch whatever happened (G-11: no retry storms).
+import { spawn } from "node:child_process";
+import { appendFileSync, closeSync, openSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { sendAgentEvents } from "./api.mjs";
+import { ensureDir, paths, readConfig } from "./config.mjs";
+import { transcriptUsage } from "./tokens.mjs";
+
+export const FLUSH_EVERY_MS = 15_000;
+const URGENT = new Set(["waiting", "finished", "error"]); // "needs you" / "done": send now
+const CLI = fileURLToPath(new URL("../bin/meksus.mjs", import.meta.url));
+
+export function record(event) {
+  ensureDir();
+  appendFileSync(paths().spool, `${JSON.stringify(event)}\n`);
+  if (URGENT.has(event.state) || event.ended || msSinceFlush() > FLUSH_EVERY_MS) startFlusher();
+}
+
+function msSinceFlush() {
+  try { return Date.now() - statSync(paths().lastFlush).mtimeMs; } catch { return Infinity; }
+}
+
+export function startFlusher() {
+  try {
+    spawn(process.execPath, [CLI, "flush"], { detached: true, stdio: "ignore", windowsHide: true, env: process.env }).unref();
+  } catch { /* next event will try again */ }
+}
+
+export async function flush() {
+  const p = paths();
+  if (!acquireLock(p.lock)) return 0;
+  try {
+    const sending = `${p.spool}.${process.pid}.sending`;
+    try { renameSync(p.spool, sending); } catch { return 0; } // nothing spooled
+    touch(p.lastFlush);
+    const lines = readFileSync(sending, "utf8").split("\n").filter(Boolean);
+    rmSync(sending, { force: true });
+
+    const events = lines.map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter((e) => e?.project);
+    const config = readConfig();
+    if (!events.length || !config?.session) return 0; // signed out, or no .meksus: status is simply discarded
+    let status = 0;
+    for (const project of new Set(events.map((e) => e.project))) {
+      const rows = aggregate(events.filter((e) => e.project === project));
+      if (rows.length) status = await sendAgentEvents(rows, { project, config });
+    }
+    return status;
+  } finally {
+    rmSync(p.lock, { force: true });
+  }
+}
+
+/** One row per session: latest state wins, deltas are summed, token totals read from the transcript. */
+export function aggregate(events) {
+  const bySession = new Map();
+  for (const e of events.sort((a, b) => a.at.localeCompare(b.at))) {
+    const cur = bySession.get(e.session) ?? {
+      session: e.session, agent: e.agent, label: e.label ?? null, state: e.state, started_at: e.started_at ?? e.at,
+      at: e.at, activity_at: e.at, tool_calls: 0, tool_failures: 0, input_tokens: 0, output_tokens: 0,
+      exit_code: null, ended: false, transcript: null, project: e.project,
+    };
+    cur.state = e.state;
+    cur.at = e.at;
+    cur.activity_at = e.activity_at ?? e.at;
+    cur.label = e.label ?? cur.label;
+    cur.tool_calls += e.tool_call ? 1 : 0;
+    cur.tool_failures += e.tool_failure ? 1 : 0;
+    if (e.exit_code !== undefined && e.exit_code !== null) cur.exit_code = e.exit_code;
+    if (e.ended) cur.ended = true;
+    if (e.transcript) cur.transcript = e.transcript;
+    if (e.started_at && e.started_at < cur.started_at) cur.started_at = e.started_at;
+    if (typeof e.task === "string") {
+      Object.assign(cur, { task: e.task, task_source: e.task_source, task_done: e.task_done ?? 0, task_total: e.task_total ?? 0, task_at: e.at });
+      // Every distinct line in the batch, for the agent's live feed (not just the last one).
+      const log = (cur.task_log ??= []);
+      if (log.at(-1)?.task !== e.task) log.push({ at: e.at, task: e.task, done: e.task_done ?? 0, total: e.task_total ?? 0 });
+      if (log.length > 30) log.splice(0, log.length - 30);
+    }
+    if (typeof e.file_path === "string") {
+      const files = (cur.files ??= []).filter((f) => f.path !== e.file_path);
+      files.push({ path: e.file_path, action: e.file_action === "read" ? "read" : "edit", at: e.at });
+      cur.files = files.slice(-20);
+    }
+    bySession.set(e.session, cur);
+  }
+  return [...bySession.values()].map(({ transcript, project, ...row }) => {
+    if (transcript) Object.assign(row, transcriptUsage(transcript)); // counted locally; only numbers leave
+    return row;
+  });
+}
+
+function acquireLock(lock) {
+  try {
+    closeSync(openSync(lock, "wx"));
+    return true;
+  } catch {
+    try {
+      if (Date.now() - statSync(lock).mtimeMs > 30_000) { rmSync(lock, { force: true }); closeSync(openSync(lock, "wx")); return true; }
+    } catch { /* someone else got it */ }
+    return false;
+  }
+}
+
+function touch(file) {
+  try { utimesSync(file, new Date(), new Date()); } catch { writeFileSync(file, ""); }
+}

package/src/tasks.mjs

@@ -0,0 +1,169 @@
+// "What is the agent working on right now", in one line (opt-in per machine: `meksus task-lines`).
+//
+// The line comes from the agent's OWN step list, not from your prompt: when Claude Code breaks work into
+// steps it writes a to-do list (TodoWrite, or the newer TaskCreate / TaskUpdate tools) and marks one step
+// in progress at a time. The hook sees those tool calls, so the step title ("Running the test suite") and
+// its position ("3 of 5") are all that's sent. When no step is in progress (or the agent has no to-do tool,
+// e.g. some IDE sessions), the line follows the agent's actions instead: the plain-English label it gives each
+// command ("Build and deploy the web app"), or "Editing app.js" (a file's name, never its path or contents).
+// Mode "prompt" also sends the first line of each prompt (clipped, and scrubbed like incident text on the
+// server). Nothing to say → no line (the dashboard shows nothing rather than a placeholder).
+//   off     nothing (default)
+//   steps   step titles, else the current action
+//   prompt  the same, plus the first line of each prompt
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { dir, readConfig, writeConfig } from "./config.mjs";
+
+export const MODES = ["off", "steps", "prompt"];
+const MAX_LINE = 140;
+const MAX_TASKS = 200;
+
+export const taskMode = (config = readConfig()) => (MODES.includes(config?.task_lines) ? config.task_lines : "off");
+
+const oneLine = (s) => (typeof s === "string" ? s.replace(/\s+/g, " ").trim().slice(0, MAX_LINE) : "");
+
+/** First meaningful line of a prompt: skips blank lines and code fences; never the whole prompt. */
+export function promptLine(prompt) {
+  if (typeof prompt !== "string") return null;
+  let fenced = false;
+  for (const raw of prompt.split(/\r?\n/)) {
+    const l = raw.trim();
+    if (l.startsWith("```")) { fenced = !fenced; continue; }
+    if (!l || fenced) continue;
+    return oneLine(l.replace(/^[#>*\-\s]+/, "")) || null;
+  }
+  return null;
+}
+
+/** TodoWrite: the in-progress item's present-tense label, and how far along the list is. */
+export function fromTodos(todos) {
+  if (!Array.isArray(todos) || !todos.length) return null;
+  const items = todos.filter((t) => t && typeof t === "object");
+  const done = items.filter((t) => t.status === "completed").length;
+  const current = items.find((t) => t.status === "in_progress");
+  if (current) return { task: oneLine(current.activeForm || current.content), task_source: "step", task_done: done, task_total: items.length };
+  if (done === items.length) return { task: `All ${items.length} steps done`, task_source: "step", task_done: done, task_total: items.length };
+  return null;
+}
+
+// TaskCreate / TaskUpdate carry only an id on update, so titles are remembered per session, locally.
+const mapFile = (session) => join(dir(), "tasks", `${session}.json`);
+function readMap(session) { try { return JSON.parse(readFileSync(mapFile(session), "utf8")); } catch { return { next: 1, tasks: {} }; } }
+function writeMap(session, map) {
+  mkdirSync(join(dir(), "tasks"), { recursive: true });
+  const ids = Object.keys(map.tasks);
+  if (ids.length > MAX_TASKS) for (const id of ids.slice(0, ids.length - MAX_TASKS)) delete map.tasks[id];
+  writeFileSync(mapFile(session), JSON.stringify(map));
+}
+
+function progress(map, line) {
+  const all = Object.values(map.tasks).filter((t) => t.status !== "deleted");
+  return { task: line, task_source: "step", task_done: all.filter((t) => t.status === "completed").length, task_total: all.length };
+}
+
+// A step is in progress: the step title wins over the action line.
+const stepActive = (map) => map.todo_active === true || Object.values(map.tasks).some((t) => t.status === "in_progress");
+
+const fileName = (p) => (typeof p === "string" && p ? basename(p.replace(/\\/g, "/")).slice(0, 80) : null);
+
+/** The action line for one tool call, or null when the tool says nothing useful (the last line stays). */
+export function actionLine(tool, args = {}) {
+  const described = oneLine(args.description);
+  switch (tool) {
+    case "Bash": case "PowerShell": return described || "Running a command";
+    case "Agent": case "Task": return described || "Working with a sub-agent";
+    case "Edit": case "MultiEdit": case "Write": case "NotebookEdit": {
+      const f = fileName(args.file_path ?? args.notebook_path);
+      return f ? `Editing ${f}` : "Editing code";
+    }
+    case "Read": { const f = fileName(args.file_path); return f ? `Reading ${f}` : "Reading code"; }
+    case "Grep": case "Glob": return "Searching the code";
+    case "WebFetch": case "WebSearch": return "Looking something up on the web";
+    default: return null;
+  }
+}
+const action = (line) => (line ? { task: line, task_source: "step", task_done: 0, task_total: 0 } : null);
+
+function createdId(response) {
+  const text = typeof response === "string" ? response : JSON.stringify(response ?? "");
+  const m = /"id"\s*:\s*"?(\d+)|#(\d+)/.exec(text);
+  return m ? m[1] ?? m[2] : null;
+}
+
+/** The task fields for one hook payload, or null when it says nothing about the current step. */
+export function taskFrom(input, session, mode) {
+  if (mode === "off") return null;
+  const tool = input?.tool_name;
+  const args = input?.tool_input ?? {};
+  const event = input?.hook_event_name;
+
+  if (event === "PreToolUse" && tool === "TodoWrite") {
+    const line = fromTodos(args.todos);
+    const map = readMap(session);
+    const active = Array.isArray(args.todos) && args.todos.some((t) => t?.status === "in_progress");
+    if (map.todo_active !== active) { map.todo_active = active; writeMap(session, map); }
+    return line;
+  }
+
+  if (event === "PostToolUse" && tool === "TaskCreate") {
+    const map = readMap(session);
+    const id = createdId(input.tool_response) ?? String(map.next);
+    map.tasks[id] = { subject: oneLine(args.subject), active: oneLine(args.activeForm), status: "pending" };
+    map.next = Math.max(map.next, Number(id) + 1 || map.next + 1);
+    writeMap(session, map);
+    return null; // created, not started
+  }
+
+  if (event === "PreToolUse" && tool === "TaskUpdate" && args.taskId !== undefined) {
+    const map = readMap(session);
+    const id = String(args.taskId);
+    const t = (map.tasks[id] ??= { subject: "", active: "", status: "pending" });
+    if (args.subject) t.subject = oneLine(args.subject);
+    if (args.activeForm) t.active = oneLine(args.activeForm);
+    if (args.status) t.status = args.status;
+    writeMap(session, map);
+    if (args.status === "in_progress") return progress(map, t.active || t.subject || `Step ${id}`);
+    if (args.status === "completed") {
+      const next = Object.values(map.tasks).find((x) => x.status === "in_progress");
+      const all = Object.values(map.tasks).filter((x) => x.status !== "deleted");
+      if (next) return progress(map, next.active || next.subject);
+      if (all.length && all.every((x) => x.status === "completed")) return progress(map, `All ${all.length} steps done`);
+      return progress(map, `Done: ${t.subject || `step ${id}`}`);
+    }
+    return null;
+  }
+
+  // Any other tool call: follow the action, unless a to-do step is in progress.
+  if (event === "PreToolUse" && tool && !["TaskCreate", "TaskUpdate", "TaskList", "TaskGet"].includes(tool)) {
+    const line = actionLine(tool, args);
+    return line && !stepActive(readMap(session)) ? action(line) : null;
+  }
+
+  if (event === "UserPromptSubmit" && mode === "prompt") {
+    const line = promptLine(input.prompt);
+    return line ? { task: line, task_source: "prompt", task_done: 0, task_total: 0 } : null;
+  }
+  if (event === "SessionEnd") { try { rmSync(mapFile(session), { force: true }); } catch { /* ignore */ } }
+  return null;
+}
+
+/** `meksus task-lines [off|steps|prompt]` */
+export function taskLinesCommand(args) {
+  const want = args[0];
+  const config = readConfig() ?? {};
+  if (!want) {
+    console.log(`Task lines: ${taskMode(config)}  (off | steps | prompt)`);
+    console.log("  steps   the step Claude Code is on (from its own to-do list), e.g. \"Running the test suite · 3 of 5\";");
+    console.log("          with no step in progress, its current action, e.g. \"Build and deploy the web app\" or \"Editing app.js\"");
+    console.log("  prompt  the same, plus the first line of each prompt");
+    return 0;
+  }
+  if (!MODES.includes(want)) { console.error("Usage: meksus task-lines off | steps | prompt"); return 2; }
+  writeConfig({ ...config, task_lines: want });
+  console.log(want === "off"
+    ? "✔ Task lines off: only status, timings and token counts are sent."
+    : `✔ Task lines: ${want}. The Agents page shows what Claude is working on (its step titles, else its current action${want === "prompt" ? ", and each prompt's first line" : ""}). Code and output still never leave this machine.`);
+  return 0;
+}
+

package/src/tokens.mjs

@@ -0,0 +1,85 @@
+// Token usage for a Claude Code session, read locally from its transcript (JSONL) and from the
+// subagent transcripts next to it, if any. Only counts leave the machine: per-model token numbers,
+// the model id, and the current context size. Never message text.
+// Assistant messages can appear several times while streaming, so usage is de-duplicated by message
+// id (last one wins).
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const MAX_BYTES = 64 * 1024 * 1024; // skip absurdly large transcripts rather than stall
+const MODEL_ID = /^[a-z0-9][a-z0-9.\-[\]]{0,62}$/;
+
+function readUsage(file, into) {
+  try {
+    if (statSync(file).size > MAX_BYTES) return null;
+  } catch {
+    return null;
+  }
+  let last = null;
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.includes('"usage"')) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    const msg = entry?.message;
+    if (entry?.type !== "assistant" || !msg?.usage) continue;
+    // "<synthetic>" (Claude Code's own placeholder messages) and malformed ids are skipped.
+    const model = msg.model === undefined ? "unknown" : typeof msg.model === "string" && MODEL_ID.test(msg.model) ? msg.model : null;
+    if (!model) continue;
+    const row = { model, usage: msg.usage };
+    into.set(msg.id ?? entry.uuid ?? `${file}:${into.size}`, row);
+    last = row;
+  }
+  return last;
+}
+
+/**
+ * {input_tokens, output_tokens, model, context_tokens, usage:{"<model>[@fast]": {in,out,cw5,cw1h,cr,ws}}}
+ * or {} when there's nothing to report.
+ */
+export function transcriptUsage(transcriptPath) {
+  try {
+    const messages = new Map();
+    const last = readUsage(transcriptPath, messages);
+    // Subagents (Task tool) write their own transcripts in <session>/subagents/*.jsonl.
+    const subDir = join(transcriptPath.replace(/\.jsonl$/, ""), "subagents");
+    try {
+      for (const f of readdirSync(subDir)) if (f.endsWith(".jsonl")) readUsage(join(subDir, f), messages);
+    } catch { /* no subagents */ }
+    if (!messages.size) return {};
+
+    const usage = {};
+    let input = 0;
+    let output = 0;
+    for (const { model, usage: u } of messages.values()) {
+      const key = u.speed === "fast" ? `${model}@fast` : model;
+      const m = (usage[key] ??= { in: 0, out: 0, cw5: 0, cw1h: 0, cr: 0, ws: 0 });
+      const cacheWrite = u.cache_creation_input_tokens ?? 0;
+      const cw1h = u.cache_creation?.ephemeral_1h_input_tokens ?? 0;
+      m.in += u.input_tokens ?? 0;
+      m.out += u.output_tokens ?? 0;
+      m.cw1h += cw1h;
+      m.cw5 += Math.max(0, cacheWrite - cw1h); // unlabelled cache writes are 5-minute writes
+      m.cr += u.cache_read_input_tokens ?? 0;
+      m.ws += u.server_tool_use?.web_search_requests ?? 0;
+      input += (u.input_tokens ?? 0) + cacheWrite + (u.cache_read_input_tokens ?? 0);
+      output += u.output_tokens ?? 0;
+    }
+    const lu = last?.usage;
+    return {
+      input_tokens: input,
+      output_tokens: output,
+      model: last?.model ?? null,
+      // What the model saw on its latest turn = the session's current context size.
+      context_tokens: lu ? (lu.input_tokens ?? 0) + (lu.cache_creation_input_tokens ?? 0) + (lu.cache_read_input_tokens ?? 0) : 0,
+      usage,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** Kept for callers of the M4 API: just the two totals. */
+export function tokenTotals(transcriptPath) {
+  const { input_tokens, output_tokens } = transcriptUsage(transcriptPath);
+  return input_tokens === undefined ? {} : { input_tokens, output_tokens };
+}

package/src/version.mjs

@@ -0,0 +1,4 @@
+// The CLI's version, from its package.json (works from a clone and from a global npm install).
+import { readFileSync } from "node:fs";
+
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/src/watch.mjs

@@ -0,0 +1,90 @@
+// `meksus watch [--label <name>] -- <command> [args…]`
+// Runs any process (a test run, a dev server, Codex, …) and reports its status: working while it runs,
+// its last output time (so the dashboard can say "quiet for 6 min"), and how it ended. Output is
+// passed straight through to your terminal and never sent. A non-zero exit opens an incident.
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { basename } from "node:path";
+import { sendAgentEvents } from "./api.mjs";
+import { PREVIEW_TEXT } from "./access.mjs";
+import { readConfig } from "./config.mjs";
+import { readProjectFile } from "./project.mjs";
+
+const HEARTBEAT_MS = 60_000; // ≤ 1 request per minute while running (G-1/G-2)
+
+export async function watch(argv) {
+  const sep = argv.indexOf("--");
+  const opts = sep >= 0 ? argv.slice(0, sep) : [];
+  const cmd = sep >= 0 ? argv.slice(sep + 1) : argv;
+  if (!cmd.length) { console.error("Usage: meksus watch [--label <name>] -- <command> [args…]"); return 2; }
+
+  const labelIdx = opts.indexOf("--label");
+  // Default label: program + first non-flag argument ("npm test"), never the full command line (args can hold secrets).
+  const label = (labelIdx >= 0 ? opts[labelIdx + 1] : [basename(cmd[0]).replace(/\.(cmd|exe|bat)$/i, ""), cmd[1] && !cmd[1].startsWith("-") ? cmd[1] : null].filter(Boolean).join(" ")).slice(0, 80);
+
+  const config = readConfig();
+  const project = readProjectFile()?.id;
+  const denied = config?.access?.ok === false; // learned from login, status or a 403 (re-checked hourly)
+  const reporting = Boolean(config?.session && project && !denied);
+  if (!config?.session) console.error("meksus: not signed in. Running without reporting (run `meksus login`).");
+  else if (denied) console.error(`meksus: ${PREVIEW_TEXT} Running without reporting.`);
+  else if (!project) console.error("meksus: this repo has no .meksus file. Running without reporting (run `meksus project use <owner/project>`).");
+
+  const session = randomBytes(16).toString("hex");
+  const startedAt = new Date().toISOString();
+  let lastOutput = startedAt;
+  const report = (state, extra = {}) =>
+    reporting
+      ? sendAgentEvents([{ session, agent: "watch", label, state, started_at: startedAt, at: new Date().toISOString(), activity_at: lastOutput, ...extra }], { project, config: readConfig(), timeoutMs: 5000 })
+      : Promise.resolve(0);
+
+  report("working");
+
+  const child = await start(cmd);
+  const onOutput = (target) => (chunk) => { lastOutput = new Date().toISOString(); target.write(chunk); };
+  child.stdout?.on("data", onOutput(process.stdout));
+  child.stderr?.on("data", onOutput(process.stderr));
+
+  // Alive heartbeat. If the process went silent, activity_at stays old and the dashboard shows "quiet".
+  const beat = setInterval(() => report("working"), HEARTBEAT_MS);
+
+  const forward = (sig) => () => child.kill(sig);
+  process.on("SIGINT", forward("SIGINT"));
+  process.on("SIGTERM", forward("SIGTERM"));
+
+  const code = await new Promise((resolve) => {
+    child.on("error", (err) => { console.error(`meksus: could not start ${cmd[0]}: ${err.message}`); resolve(127); });
+    child.on("close", (c, signal) => resolve(c ?? (signal ? 128 : 1)));
+  });
+  clearInterval(beat);
+  await report(code === 0 ? "finished" : "error", { exit_code: code, ended: true });
+  return code;
+}
+
+// ── Process start without a shell (arguments stay exactly as typed) ──────────
+const OPTIONS = { stdio: ["inherit", "pipe", "pipe"], env: { ...process.env, FORCE_COLOR: process.env.FORCE_COLOR ?? "1" } };
+
+/** Direct spawn; on Windows, if the program isn't an .exe on PATH (npm, npx, … are .cmd shims), retry via cmd.exe with escaped args. */
+function start(cmd) {
+  return new Promise((resolve) => {
+    const direct = spawn(cmd[0], cmd.slice(1), OPTIONS);
+    direct.once("spawn", () => resolve(direct));
+    direct.once("error", (err) => {
+      if (process.platform !== "win32" || err.code !== "ENOENT") return resolve(direct);
+      const line = [escapeCommand(cmd[0]), ...cmd.slice(1).map((a) => escapeArg(a, true))].join(" ");
+      resolve(spawn(process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", `"${line}"`], { ...OPTIONS, windowsVerbatimArguments: true }));
+    });
+  });
+}
+
+// cmd.exe escaping (same rules as cross-spawn): quote for CommandLineToArgvW, then caret-escape cmd
+// metacharacters; .cmd shims re-parse their arguments, so those need escaping twice.
+const META = /([()\][%!^"`<>&|;, *?])/g;
+export function escapeCommand(s) {
+  return s.replace(META, "^$1");
+}
+export function escapeArg(arg, doubleEscape = false) {
+  let a = `${arg}`.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"').replace(/(?=(\\+?)?)\1$/, "$1$1");
+  a = `"${a}"`.replace(META, "^$1");
+  return doubleEscape ? a.replace(META, "^$1") : a;
+}