@sealant/mend 0.1.0 → 0.1.1

package/dist/main.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
+import { createRequire } from "node:module";
 import * as os from "node:os";
 import * as path from "node:path";
+import { CONTINUE_COMMANDS, gitTopLevel, HARNESS_COMMANDS, LIVE_STATUSES, matchProjectByCwd, normalizeProjectName, } from "./shared.js";
 const CONFIG_PATH = path.join(os.homedir(), ".mend", "cli.json");
 const loadConfig = () => {
     let fileConfig = {};
@@ -28,7 +31,41 @@ const green = paint("32");
 const amber = paint("33");
 const cobalt = paint("34");
 const say = (line) => process.stdout.write(`${line}\n`);
-const api = async (config, method, route, body) => {
+const detachKeyEnabled = process.env["MEND_DETACH_KEY"] !== "none";
+const detachHint = () => (detachKeyEnabled ? ` · detach: ${dim("Ctrl+]")}` : "");
+const herdrAgentOf = (harness) => {
+    if (harness === "codex" || harness === "claude" || harness === "opencode")
+        return harness;
+    return null;
+};
+const hintHerdrAttachment = (harness) => {
+    const agent = herdrAgentOf(harness);
+    if (process.env["HERDR_ENV"] !== "1" || agent === null)
+        return () => undefined;
+    // Herdr deliberately reads HERDR_AGENT from any member of the foreground
+    // process group. A pipe-tethered child carries the hint while Mend owns the
+    // pane, without claiming lifecycle authority: Herdr's native screen rules
+    // still derive working, idle, and blocked from the bridged agent UI.
+    const carrier = spawn(process.execPath, ["-e", "process.stdin.resume();process.stdin.once('end',()=>process.exit(0))"], {
+        env: { ...process.env, HERDR_AGENT: agent },
+        stdio: ["pipe", "ignore", "ignore"],
+    });
+    let stopped = false;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        carrier.stdin?.end();
+        carrier.kill();
+    };
+    process.once("exit", stop);
+    return () => {
+        process.off("exit", stop);
+        stop();
+    };
+};
+/** The raw server call — THROWS with a human message; the dashboard renders it. */
+const request = async (config, method, route, body) => {
     const headers = { "content-type": "application/json" };
     if (config.token !== null)
         headers["authorization"] = `Bearer ${config.token}`;
@@ -42,23 +79,34 @@ const api = async (config, method, route, body) => {
         });
     }
     catch {
-        return fail(`cannot reach the Mend server at ${config.url} — is it running?`);
+        throw new Error(`cannot reach the Mend server at ${config.url} — is it running?`);
     }
     if (response.status === 401) {
-        return fail(`unauthorized — set MEND_TOKEN (or "token" in ${CONFIG_PATH}) to a bearer token for ${config.url}`);
+        throw new Error(`unauthorized — set MEND_TOKEN (or "token" in ${CONFIG_PATH}) to a bearer token for ${config.url}`);
     }
     const text = await response.text();
     if (!response.ok) {
+        let message = `${method} ${route} → ${response.status}`;
         try {
             const parsed = JSON.parse(text);
-            return fail(parsed.message ?? `${method} ${route} → ${response.status}`);
+            message = parsed.message ?? message;
         }
         catch {
-            return fail(`${method} ${route} → ${response.status}`);
+            // not JSON — keep the status line
         }
+        throw new Error(message);
     }
     return JSON.parse(text);
 };
+/** The same call for one-shot commands: any failure prints and exits. */
+const api = async (config, method, route, body) => {
+    try {
+        return await request(config, method, route, body);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+};
 const worktreePathOf = (storePath, worktree) => path.join(path.dirname(storePath), "worktrees", worktree);
 /** A live elapsed-time spinner around a slow await — provisioning is not a hang. */
 const withSpinner = async (label, work) => {
@@ -85,9 +133,11 @@ const adopt = async (config, args) => {
     const nameFlag = args.indexOf("--name");
     const name = nameFlag !== -1 && args[nameFlag + 1] !== undefined ? String(args[nameFlag + 1]) : null;
     const positional = args.filter((a, i) => !a.startsWith("--") && (nameFlag === -1 || i !== nameFlag + 1));
-    const rawSource = positional[0] ?? ".";
+    // Bare `mend adopt` adopts the repo the cwd is inside, not the subdirectory.
+    const rawSource = positional[0] ?? gitTopLevel(process.cwd()) ?? ".";
     const source = /^(https?|git|ssh):|^git@/.test(rawSource) ? rawSource : path.resolve(rawSource);
-    const projectName = name ?? path.basename(source, ".git");
+    // Derived defaults are normalized ("Mend" → "mend"); explicit --name is sent as typed.
+    const projectName = name ?? normalizeProjectName(path.basename(source, ".git"));
     const project = await api(config, "POST", "/projects", {
         name: projectName,
         source,
@@ -97,7 +147,7 @@ const adopt = async (config, args) => {
     say(`${dim("  sessions start with:")} mend codex ${dim("(from anywhere —")} --project ${project.name}${dim(")")}`);
 };
 // ─── session launch ─────────────────────────────────────────────────────────
-const findProject = async (config, explicit) => {
+const findProject = async (config, explicit, adoptCwd = false) => {
     const projects = await api(config, "GET", "/projects");
     if (explicit !== null) {
         const named = projects.find((p) => p.name === explicit);
@@ -106,18 +156,24 @@ const findProject = async (config, explicit) => {
         return named;
     }
     const cwd = process.cwd();
-    const byOrigin = projects.find((p) => p.originUrl !== null && cwd.startsWith(p.originUrl));
-    const byName = projects.find((p) => p.name === path.basename(cwd));
-    const project = byOrigin ?? byName;
-    if (project === undefined) {
+    const project = matchProjectByCwd(projects, cwd);
+    if (project !== undefined)
+        return project;
+    if (!adoptCwd) {
         return fail(`no adopted project matches ${cwd} — run "mend adopt" here first, or name one with --project`);
     }
-    return project;
-};
-const HARNESS_COMMANDS = {
-    codex: ["codex"],
-    claude: ["claude"],
-    opencode: ["opencode"],
+    // Launching from an un-adopted repo just adopts it — adoption is cheap and
+    // has no ceremony to deserve a separate errand.
+    const top = gitTopLevel(cwd);
+    if (top === null) {
+        return fail(`${cwd} is not inside a git repository — mend adopt <source> adopts one explicitly`);
+    }
+    const adopted = await api(config, "POST", "/projects", {
+        name: normalizeProjectName(path.basename(top)),
+        source: top,
+    });
+    say(`${green("✓")} adopted · ${adopted.name} · ${dim(adopted.storePath)}`);
+    return adopted;
 };
 const launch = async (config, harness, args) => {
     const projectFlag = args.indexOf("--project");
@@ -130,7 +186,7 @@ const launch = async (config, harness, args) => {
     if (argv.length === 0) {
         return fail(harness === "run" ? "usage: mend run -- <command...>" : `unknown harness ${harness}`);
     }
-    const project = await findProject(config, explicit);
+    const project = await findProject(config, explicit, true);
     const session = await api(config, "POST", `/projects/${project.id}/sessions`, {
         harness,
         label: null,
@@ -146,14 +202,10 @@ const launch = async (config, harness, args) => {
         return supervisedRun(config, session, argv);
     }
     await withSpinner("provisioning workspace — a first launch builds the harness image (can take minutes)…", api(config, "POST", `/sessions/${session.id}/launch`, { argv }));
-    say(`${green("✓ recording")} · workspace mounts the worktree · detach: ${dim("Ctrl+]")}`);
+    say(`${green("✓ recording")} · workspace mounts the worktree${detachHint()}`);
     say("");
-    await attachTty(config, session.id, 0n);
-    const settled = await api(config, "GET", `/sessions/${session.id}`);
-    say("");
-    say(`${green("✓")} session ${settled.session.status} · recorded`);
-    say(`${cobalt("  review")} · ${config.url}/sessions/${session.id}`);
-    process.exit(0);
+    await attachOrExit(config, session.id, session.harness);
+    exitAfterSessionEnd(config, session.id);
 };
 // ─── the terminal bridge: raw stdin/stdout against the platform PTY ─────────
 /**
@@ -162,9 +214,11 @@ const launch = async (config, harness, args) => {
  * JSON (resize up, end down). Auth happens once at connect (?token=); after
  * that a keystroke is a frame on an open socket — nothing else on the path.
  * Ctrl+] detaches — the session keeps running and can be reattached from
- * anywhere. Resolves when the session settles or the user detaches.
+ * anywhere. Resolves when the session settles or the user detaches; the
+ * caller decides what each outcome means (commands exit, the dashboard
+ * resumes).
  */
-const attachTty = async (config, sessionId, from) => {
+const attachTty = async (config, sessionId, harness, from) => {
     const url = new URL(`${config.url}/api/tty`);
     url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
     url.searchParams.set("session", sessionId);
@@ -180,51 +234,108 @@ const attachTty = async (config, sessionId, from) => {
         });
     }
     catch {
-        return fail(`tty attach unavailable: could not connect to ${url.host}`);
-    }
-    const sendResize = () => ws.send(JSON.stringify({
-        t: "resize",
-        cols: process.stdout.columns ?? 80,
-        rows: process.stdout.rows ?? 24,
-    }));
-    sendResize();
+        return "unavailable";
+    }
+    const stopHerdrHint = hintHerdrAttachment(harness);
+    let finishAttachment;
+    const finished = new Promise((resolve) => {
+        finishAttachment = resolve;
+    });
+    const onClose = () => finishAttachment?.();
+    if (ws.readyState === WebSocket.CLOSED)
+        finishAttachment?.();
+    else
+        ws.addEventListener("close", onClose, { once: true });
+    const sendResize = () => {
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
+        ws.send(JSON.stringify({
+            t: "resize",
+            cols: process.stdout.columns ?? 80,
+            rows: process.stdout.rows ?? 24,
+        }));
+    };
     const onWinch = () => sendResize();
-    process.stdout.on("resize", onWinch);
     const rawTty = process.stdin.isTTY === true;
-    if (rawTty)
-        process.stdin.setRawMode(true);
-    process.stdin.resume();
+    let rawModeEnabled = false;
     let detached = false;
+    const onTtyFrame = (event) => {
+        if (typeof event.data !== "string") {
+            process.stdout.write(Buffer.from(event.data));
+            return;
+        }
+        try {
+            const frame = JSON.parse(event.data);
+            if (typeof frame !== "object" || frame === null || !("t" in frame) || frame.t !== "end") {
+                return;
+            }
+            // Session lifecycle is authoritative. Start detaching immediately instead
+            // of holding the user's terminal for the later close handshake and Mend's
+            // settle/checkpoint/harvest work.
+            ws.close();
+            finishAttachment?.();
+        }
+        catch {
+            // Unknown text control frame — ignore.
+        }
+    };
     const onKeys = (data) => {
-        if (data.includes(0x1d)) {
+        if (detachKeyEnabled && data.includes(0x1d)) {
             // Ctrl+] — detach, leave the session running.
             detached = true;
             ws.close();
             return;
         }
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
         // Copy into a plain ArrayBuffer (WebSocket.send rejects pooled Buffer views).
         ws.send(new Uint8Array(data).buffer);
     };
-    process.stdin.on("data", onKeys);
-    ws.addEventListener("message", (event) => {
-        if (typeof event.data === "string")
-            return; // control frames ({"t":"end"}) — close follows
-        process.stdout.write(Buffer.from(event.data));
-    });
-    await new Promise((resolve) => {
-        ws.addEventListener("close", () => resolve(), { once: true });
-    });
-    process.stdin.off("data", onKeys);
-    process.stdout.off("resize", onWinch);
-    if (rawTty)
-        process.stdin.setRawMode(false);
-    process.stdin.pause();
-    if (detached) {
+    try {
+        sendResize();
+        process.stdout.on("resize", onWinch);
+        if (rawTty) {
+            process.stdin.setRawMode(true);
+            rawModeEnabled = true;
+        }
+        process.stdin.resume();
+        process.stdin.on("data", onKeys);
+        ws.addEventListener("message", onTtyFrame);
+        await finished;
+        return detached ? "detached" : "ended";
+    }
+    finally {
+        process.stdin.off("data", onKeys);
+        process.stdout.off("resize", onWinch);
+        ws.removeEventListener("message", onTtyFrame);
+        ws.removeEventListener("close", onClose);
+        if (rawModeEnabled)
+            process.stdin.setRawMode(false);
+        process.stdin.pause();
+        if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)
+            ws.close();
+        stopHerdrHint();
+    }
+};
+/** How every one-shot command handles an attach outcome: detach says so, settle returns. */
+const finishAttach = (config, sessionId, outcome) => {
+    if (outcome === "unavailable") {
+        return fail(`tty attach unavailable: could not connect to ${config.url}`);
+    }
+    if (outcome === "detached") {
         say("");
         say(`${amber("detached")} — the session keeps running; reattach: mend attach ${sessionId.slice(0, 8)}`);
         process.exit(0);
     }
 };
+const attachOrExit = async (config, sessionId, harness) => finishAttach(config, sessionId, await attachTty(config, sessionId, harness, 0n));
+/** Return terminal control as soon as the terminal reports the observed end. */
+const exitAfterSessionEnd = (config, sessionId) => {
+    say("");
+    say(`${green("✓")} session ended`);
+    say(`${cobalt("  review")} · ${config.url}/sessions/${sessionId}`);
+    process.exit(0);
+};
 /** Reattach a terminal to a running session (full scrollback replay, then live). */
 const attach = async (config, args) => {
     const prefix = args.find((a) => !a.startsWith("--"));
@@ -234,12 +345,10 @@ const attach = async (config, args) => {
     const match = sessions.find((s) => s.id.startsWith(prefix));
     if (match === undefined)
         return fail(`no active session matches "${prefix}"`);
-    say(`${green("✓")} attaching to ${match.harness} · ${dim(match.id.slice(0, 8))} · detach: ${dim("Ctrl+]")}`);
-    say("");
-    await attachTty(config, match.id, 0n);
+    say(`${green("✓")} attaching to ${match.harness} · ${dim(match.id.slice(0, 8))}${detachHint()}`);
     say("");
-    say(`${green("✓")} session settled`);
-    process.exit(0);
+    await attachOrExit(config, match.id, match.harness);
+    exitAfterSessionEnd(config, match.id);
 };
 // ─── supervised run: platform workspace + PTY + record ──────────────────────
 const supervisedRun = async (config, session, argv) => {
@@ -299,12 +408,6 @@ const supervisedRun = async (config, session, argv) => {
     say(`${cobalt("  review")} · ${config.url}/sessions/${session.id}`);
     process.exit(settled === "failed" ? 1 : 0);
 };
-/** How each harness takes an instruction as its opening prompt. */
-const CONTINUE_COMMANDS = {
-    codex: (instruction) => ["codex", instruction],
-    claude: (instruction) => ["claude", instruction],
-    opencode: (instruction) => ["opencode", "run", instruction],
-};
 /**
  * The second half of the review loop (plan §7.3): find the session with a
  * pending follow-up, deliver it (which reopens the session), and relaunch the
@@ -364,17 +467,13 @@ const continueSession = async (config, args) => {
     // the web session page shows the live terminal throughout.
     const argv = build(followUp.instruction);
     await withSpinner("provisioning workspace — the resumed run records like any other…", api(config, "POST", `/sessions/${session.id}/launch`, { argv }));
-    say(`${green("✓ recording")} · workspace mounts the worktree · detach: ${dim("Ctrl+]")}`);
-    say("");
-    await attachTty(config, session.id, 0n);
-    const settled = await api(config, "GET", `/sessions/${session.id}`);
+    say(`${green("✓ recording")} · workspace mounts the worktree${detachHint()}`);
     say("");
-    say(`${green("✓")} session ${settled.session.status} · recorded`);
-    say(`${cobalt("  review")} · ${config.url}/sessions/${session.id}`);
-    process.exit(0);
+    await attachOrExit(config, session.id, session.harness);
+    exitAfterSessionEnd(config, session.id);
 };
 // ─── resume: rejoin a session — same worktree, restored harness state ───────
-const ACTIVE_STATUSES = new Set(["starting", "running", "waiting", "idle"]);
+const ACTIVE_STATUSES = LIVE_STATUSES;
 /**
  * Sessions are continuous work, not runs: `mend resume` rejoins one on a
  * fresh workspace — saved harness state restored, a claude resume is native
@@ -401,38 +500,251 @@ const resumeCommand = async (config, args) => {
     say(`${green("✓")} resuming ${match.harness} · ${dim(match.id.slice(0, 8))}${withHarness === null ? "" : ` ${dim("as")} ${withHarness}`}`);
     say(`${cobalt("  watch")} · ${config.url}/sessions/${match.id}`);
     await withSpinner("resuming — a fresh workspace restores the saved session state…", api(config, "POST", `/sessions/${match.id}/resume`, { harness: withHarness }));
-    say(`${green("✓ recording")} · same worktree, conversation restored · detach: ${dim("Ctrl+]")}`);
+    say(`${green("✓ recording")} · same worktree, conversation restored${detachHint()}`);
     say("");
-    await attachTty(config, match.id, 0n);
-    const settled = await api(config, "GET", `/sessions/${match.id}`);
+    await attachOrExit(config, match.id, withHarness ?? match.harness);
+    exitAfterSessionEnd(config, match.id);
+};
+// ─── rejoin: one entrypoint for an outer multiplexer ────────────────────────
+/**
+ * Idempotent entrypoint for outer multiplexers: attach when the session is
+ * live, otherwise restore and resume it before attaching. With no id, the
+ * newest live session wins, falling back to the newest settled session;
+ * --harness narrows the choice.
+ */
+const resumeForRejoin = async (config, sessionId, label) => {
+    try {
+        await withSpinner(label, request(config, "POST", `/sessions/${sessionId}/resume`, { harness: null }));
+        return true;
+    }
+    catch (error) {
+        const refreshed = await api(config, "GET", `/sessions/${sessionId}`);
+        if (ACTIVE_STATUSES.has(refreshed.session.status))
+            return false;
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+};
+const rejoinCommand = async (config, args) => {
+    const harnessFlag = args.indexOf("--harness");
+    const harness = harnessFlag !== -1 && args[harnessFlag + 1] !== undefined
+        ? String(args[harnessFlag + 1])
+        : null;
+    const prefix = args.find((arg, index) => !arg.startsWith("--") && index !== harnessFlag + 1);
+    const project = await findProject(config, null);
+    const detail = await api(config, "GET", `/projects/${project.id}`);
+    const eligible = detail.sessions
+        .filter((session) => harness === null || session.harness === harness)
+        .toSorted((left, right) => right.createdAt.localeCompare(left.createdAt));
+    const newest = eligible.find((session) => ACTIVE_STATUSES.has(session.status)) ?? eligible[0];
+    const matches = prefix === undefined
+        ? newest === undefined
+            ? []
+            : [newest]
+        : eligible.filter((session) => session.id.startsWith(prefix));
+    if (matches.length === 0) {
+        const harnessDescription = harness === null ? "" : ` ${harness}`;
+        return fail(prefix === undefined
+            ? `no${harnessDescription} session to rejoin in project ${project.name}`
+            : `no${harnessDescription} session matches "${prefix}" in project ${project.name}`);
+    }
+    if (matches.length > 1) {
+        return fail(`session prefix "${prefix}" is ambiguous — use more of the id`);
+    }
+    const session = matches[0];
+    if (session === undefined)
+        return fail("session selection failed");
+    say(`${green("✓")} rejoining ${session.harness} · ${dim(session.id.slice(0, 8))} · ${ACTIVE_STATUSES.has(session.status) ? "already live" : "restoring"}`);
+    say(`${cobalt("  watch")} · ${config.url}/sessions/${session.id}`);
+    let restored = false;
+    if (!ACTIVE_STATUSES.has(session.status)) {
+        restored = await resumeForRejoin(config, session.id, "resuming — a fresh workspace restores the saved session state…");
+    }
+    say(restored
+        ? `${green("✓ recording")} · same worktree, conversation restored${detachHint()}`
+        : `${green("✓ recording")} · attached to the live session${detachHint()}`);
     say("");
-    say(`${green("✓")} session ${settled.session.status} · recorded`);
-    say(`${cobalt("  review")} · ${config.url}/sessions/${match.id}`);
-    process.exit(0);
+    let outcome = await attachTty(config, session.id, session.harness, 0n);
+    if (outcome === "unavailable") {
+        const refreshed = await api(config, "GET", `/sessions/${session.id}`);
+        if (!ACTIVE_STATUSES.has(refreshed.session.status)) {
+            await resumeForRejoin(config, session.id, "session settled while attaching — restoring it once…");
+        }
+        outcome = await attachTty(config, session.id, session.harness, 0n);
+    }
+    finishAttach(config, session.id, outcome);
+    exitAfterSessionEnd(config, session.id);
 };
-// ─── status ─────────────────────────────────────────────────────────────────
-const status = async (config) => {
-    const sessions = await api(config, "GET", "/sessions");
-    if (sessions.length === 0) {
-        say(dim("no active sessions"));
+// ─── projects · sessions: the workbench at a glance ─────────────────────────
+const projectsCommand = async (config) => {
+    const [projects, active] = await Promise.all([
+        api(config, "GET", "/projects"),
+        api(config, "GET", "/sessions"),
+    ]);
+    if (projects.length === 0) {
+        say(dim("no adopted projects — mend adopt brings one in"));
         return;
     }
-    for (const session of sessions) {
-        say(`${session.harness}  ${dim(session.id.slice(0, 8))}  ${session.status}  ${dim(session.branch)}`);
+    const liveByProject = new Map();
+    for (const session of active) {
+        liveByProject.set(session.projectId, (liveByProject.get(session.projectId) ?? 0) + 1);
+    }
+    const nameWidth = Math.max(...projects.map((p) => p.name.length));
+    const branchWidth = Math.max(...projects.map((p) => p.defaultBranch.length));
+    for (const project of projects) {
+        const live = liveByProject.get(project.id) ?? 0;
+        const liveLabel = live > 0 ? green(`${live} live`) : dim("—");
+        say(`${project.name.padEnd(nameWidth)}  ${dim(project.defaultBranch.padEnd(branchWidth))}  ${liveLabel}  ${dim(project.storePath)}`);
+    }
+};
+const printSessionRow = (row) => {
+    const { session, annotation } = row;
+    const live = ACTIVE_STATUSES.has(session.status);
+    const status = session.status.padEnd(9);
+    const facts = [];
+    if (session.label !== null)
+        facts.push(session.label);
+    if (annotation !== undefined && annotation.openComments > 0) {
+        facts.push(amber(`${annotation.openComments} open`));
     }
+    if (annotation !== undefined && annotation.pendingFollowUp)
+        facts.push(amber("follow-up pending"));
+    say(`${session.harness.padEnd(8)}  ${dim(session.id.slice(0, 8))}  ${live ? green(status) : dim(status)}  ${row.projectName}  ${dim(session.branch)}${facts.length > 0 ? `  ${facts.join(dim(" · "))}` : ""}`);
+};
+/**
+ * Active sessions by default; --all sweeps every project's detail so settled
+ * sessions arrive with their review facts (open comments, pending follow-up).
+ */
+const sessionsCommand = async (config, args) => {
+    const all = args.includes("--all");
+    const json = args.includes("--json");
+    const projectFlag = args.indexOf("--project");
+    const projectName = projectFlag !== -1 && args[projectFlag + 1] !== undefined
+        ? String(args[projectFlag + 1])
+        : null;
+    const projects = await api(config, "GET", "/projects");
+    const scope = projectName === null ? projects : projects.filter((p) => p.name === projectName);
+    if (projectName !== null && scope.length === 0) {
+        return fail(`no adopted project named "${projectName}"`);
+    }
+    let rows;
+    if (all || projectName !== null) {
+        const details = await Promise.all(scope.map((p) => api(config, "GET", `/projects/${p.id}`)));
+        rows = details.flatMap((detail) => detail.sessions.map((session) => ({
+            session,
+            projectName: detail.project.name,
+            annotation: detail.annotations.find((a) => a.sessionId === session.id),
+        })));
+    }
+    else {
+        const active = await api(config, "GET", "/sessions");
+        const nameById = new Map(projects.map((p) => [p.id, p.name]));
+        rows = active.map((session) => ({
+            session,
+            projectName: nameById.get(session.projectId) ?? session.projectId.slice(0, 8),
+            annotation: undefined,
+        }));
+    }
+    if (rows.length === 0) {
+        if (json) {
+            say(JSON.stringify({ version: 1, sessions: [] }, null, 2));
+            return;
+        }
+        say(dim(all ? "no sessions" : "no active sessions — mend sessions --all includes settled ones"));
+        return;
+    }
+    rows.sort((a, b) => {
+        const aLive = ACTIVE_STATUSES.has(a.session.status) ? 1 : 0;
+        const bLive = ACTIVE_STATUSES.has(b.session.status) ? 1 : 0;
+        if (aLive !== bLive)
+            return bLive - aLive;
+        return b.session.createdAt.localeCompare(a.session.createdAt);
+    });
+    if (json) {
+        const payload = {
+            version: 1,
+            sessions: rows.map(({ session, projectName: rowProjectName, annotation }) => ({
+                id: session.id,
+                projectId: session.projectId,
+                projectName: rowProjectName,
+                harness: session.harness,
+                label: session.label,
+                worktree: session.worktree,
+                branch: session.branch,
+                baseSha: session.baseSha,
+                status: session.status,
+                summary: session.summary,
+                createdAt: session.createdAt,
+                reviewUrl: `${config.url.replace(/\/$/, "")}/sessions/${session.id}`,
+                review: annotation === undefined
+                    ? null
+                    : {
+                        openComments: annotation.openComments,
+                        totalComments: annotation.totalComments,
+                        pendingFollowUp: annotation.pendingFollowUp,
+                    },
+            })),
+        };
+        say(JSON.stringify(payload, null, 2));
+        return;
+    }
+    for (const row of rows)
+        printSessionRow(row);
+};
+// ─── dashboard: the live TUI on bare `mend` ─────────────────────────────────
+const hasNodeFfi = () => {
+    try {
+        createRequire(import.meta.url)("node:ffi");
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The dashboard needs @opentui/core, whose Node backend binds the native
+ * renderer over node:ffi — present from Node 26, and only behind
+ * --experimental-ffi. Gate here and re-exec the same argv with the flag so
+ * the user never types it; every other command stays on plain Node >= 22.
+ */
+const dashboard = async (config) => {
+    if (process.stdout.isTTY !== true) {
+        say(HELP);
+        return;
+    }
+    if (!hasNodeFfi()) {
+        const major = Number(process.versions.node.split(".")[0]);
+        if (Number.isNaN(major) || major < 26) {
+            return fail(`the dashboard needs Node >= 26 (node:ffi) — this is ${process.version}; every other command still works`);
+        }
+        const rerun = spawnSync(process.execPath, ["--experimental-ffi", "--disable-warning=ExperimentalWarning", ...process.argv.slice(1)], { stdio: "inherit" });
+        process.exit(rerun.status ?? 0);
+    }
+    const { runDashboard } = await import("./dashboard.js");
+    await runDashboard({
+        config,
+        cwd: process.cwd(),
+        api: (method, route, body) => request(config, method, route, body),
+        attachTty: (sessionId, harness) => attachTty(config, sessionId, harness, 0n),
+    });
 };
 // ─── entry ──────────────────────────────────────────────────────────────────
 const HELP = `mend — the agent workbench
 
+  mend                                  the dashboard: every project and session, live
   mend adopt [source] [--name <name>]   adopt a repository into the store (default: cwd)
   mend codex|claude|opencode            new session worktree + launch the harness in it
   mend run -- <command...>              same, with an arbitrary command
   mend attach <session-id-prefix>       reattach this terminal to a running session
   mend continue [session-id]            resume a session with its pending review follow-up
   mend resume [session-id] [--with h]   rejoin a settled session (state restored; --with switches harness)
-  mend status                           active sessions
+  mend rejoin [session-id] [--harness h] attach if live, otherwise resume; newest live wins
+  mend projects                         adopted projects and their live sessions
+  mend sessions [--all] [--project p] [--json]
+                                        sessions with review facts; JSON is stable for integrations
+  mend status                           active sessions (alias of mend sessions)
 
   server: MEND_URL (default http://localhost:3105) · auth: MEND_TOKEN
+  detach key: Ctrl+] (set MEND_DETACH_KEY=none when an outer multiplexer owns detaching)
   config file: ~/.mend/cli.json { "url": ..., "token": ... }
 `;
 const main = async () => {
@@ -452,9 +764,16 @@ const main = async () => {
             return continueSession(config, rest);
         case "resume":
             return resumeCommand(config, rest);
+        case "rejoin":
+            return rejoinCommand(config, rest);
+        case "projects":
+            return projectsCommand(config);
+        case "sessions":
         case "status":
-            return status(config);
+            return sessionsCommand(config, rest);
         case undefined:
+        case "ui":
+            return dashboard(config);
         case "help":
         case "--help":
             say(HELP);