@sealant/mend 0.1.0 → 0.2.0

package/dist/main.js

@@ -1,8 +1,22 @@
 #!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
-const CONFIG_PATH = path.join(os.homedir(), ".mend", "cli.json");
+import { readSyncFiles, scanDotfileCandidates } from "./dotfiles.js";
+import { isComposeFile, proposeFromCompose, proposeFromPackageJson, proposeFromWorkspacePackage, renderMendToml, workspaceGlobs, } from "./service-init.js";
+import { CONTINUE_COMMANDS, gitTopLevel, HARNESS_COMMANDS, LIVE_STATUSES, matchProjectByCwd, normalizeProjectName, } from "./shared.js";
+// `$XDG_CONFIG_HOME/mend`, default `~/.config/mend`; a pre-XDG `~/.mend` stays authoritative
+// when it is the only one present (mirrors @mend/store's resolver — the CLI stays dependency-light).
+const mendCliHome = () => {
+    const xdg = process.env["XDG_CONFIG_HOME"];
+    const preferred = path.join(xdg === undefined || xdg === "" ? path.join(os.homedir(), ".config") : xdg, "mend");
+    const legacy = path.join(os.homedir(), ".mend");
+    return !fs.existsSync(preferred) && fs.existsSync(legacy) ? legacy : preferred;
+};
+const CONFIG_PATH = path.join(mendCliHome(), "cli.json");
 const loadConfig = () => {
     let fileConfig = {};
     if (fs.existsSync(CONFIG_PATH)) {
@@ -28,7 +42,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 +90,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) => {
@@ -84,20 +143,39 @@ const withSpinner = async (label, work) => {
 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] ?? ".";
+    const authFlagIndex = args.indexOf("--auth");
+    const positional = args.filter((a, i) => !a.startsWith("--") &&
+        (nameFlag === -1 || i !== nameFlag + 1) &&
+        (authFlagIndex === -1 || i !== authFlagIndex + 1));
+    // 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 auth = authFlagIndex !== -1 && args[authFlagIndex + 1] !== undefined
+        ? String(args[authFlagIndex + 1])
+        : null;
+    if (auth !== null && auth !== "ambient" && auth !== "mend-key" && auth !== "bridge") {
+        return fail(`--auth takes "ambient", "mend-key", or "bridge", not "${auth}"`);
+    }
     const project = await api(config, "POST", "/projects", {
         name: projectName,
         source,
+        ...(auth === null ? {} : { gitAuthMode: auth }),
     });
     say(`${green("✓")} adopted · ${project.name} · ${dim(project.storePath)}`);
     say(`${dim("  default branch")} ${project.defaultBranch}`);
+    // Say which signer did the work — the clone already proved it answers.
+    if (project.gitAuthMode === "mend-key") {
+        say(`${dim("  git auth")} mend key ${dim("(the machine's deploy key signed this clone)")}`);
+    }
+    else if (project.gitAuthMode === "bridge") {
+        say(`${dim("  git auth")} bridge ${dim("(signed through the connected `mend keys share`)")}`);
+    }
     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 +184,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 +214,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 +230,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,12 +242,19 @@ 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, processId, options) => {
     const url = new URL(`${config.url}/api/tty`);
     url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-    url.searchParams.set("session", sessionId);
+    // Process addressing reaches any PTY in the workspace (a shell); the
+    // session form remains the agent's PTY.
+    if (processId !== undefined)
+        url.searchParams.set("process", processId);
+    else
+        url.searchParams.set("session", sessionId);
     url.searchParams.set("from", from.toString());
     if (config.token !== null)
         url.searchParams.set("token", config.token);
@@ -180,51 +267,112 @@ const attachTty = async (config, sessionId, from) => {
         });
     }
     catch {
-        return fail(`tty attach unavailable: could not connect to ${url.host}`);
+        return "unavailable";
     }
-    const sendResize = () => ws.send(JSON.stringify({
-        t: "resize",
-        cols: process.stdout.columns ?? 80,
-        rows: process.stdout.rows ?? 24,
-    }));
-    sendResize();
+    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);
+        // Read-only (logs): never forward stdin — Ctrl+C exits the CLI, the
+        // socket drops, and the process inside keeps running untouched.
+        if (options?.readOnly !== true) {
+            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,13 +382,707 @@ 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(`${green("✓")} attaching to ${match.harness} · ${dim(match.id.slice(0, 8))}${detachHint()}`);
     say("");
-    await attachTty(config, match.id, 0n);
+    await attachOrExit(config, match.id, match.harness);
+    exitAfterSessionEnd(config, match.id);
+};
+/** Compact picker: numbered live sessions, one keystroke of typing. */
+const pickSessionInteractively = async (rows) => {
+    say(dim("more than one live session — pick one:"));
+    rows.forEach((row, index) => {
+        say(`  ${index + 1}. ${row.session.harness.padEnd(8)} ${dim(row.session.id.slice(0, 8))}  ${row.projectName}  ${dim(row.session.branch)}`);
+    });
+    const readline = await import("node:readline/promises");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question("  session #: ");
+    rl.close();
+    const chosen = rows[Number(answer.trim()) - 1];
+    if (chosen === undefined)
+        return fail(`"${answer.trim()}" is not one of the choices`);
+    return chosen.session;
+};
+/**
+ * The resolution order (docs/SESSION-SERVICES.md): an explicit id wins, then
+ * the cwd's project narrows, one candidate is taken, several go to the
+ * picker, and a non-interactive caller never gets a silent guess.
+ */
+const resolveLiveSession = async (config, prefix) => {
+    const sessions = await api(config, "GET", "/sessions");
+    if (prefix !== undefined) {
+        const matches = sessions.filter((s) => s.id.startsWith(prefix));
+        if (matches.length === 0)
+            return fail(`no live session matches "${prefix}"`);
+        const exact = matches[0];
+        if (matches.length > 1 || exact === undefined) {
+            return fail(`session prefix "${prefix}" is ambiguous — use more of the id`);
+        }
+        return exact;
+    }
+    const projects = await api(config, "GET", "/projects");
+    const project = matchProjectByCwd(projects, process.cwd());
+    const candidates = project === undefined ? sessions : sessions.filter((s) => s.projectId === project.id);
+    const only = candidates[0];
+    if (only === undefined) {
+        return fail("no live session — start one with mend codex|claude|opencode");
+    }
+    if (candidates.length === 1)
+        return only;
+    if (process.stdin.isTTY !== true) {
+        return fail("several live sessions — name one: mend shell <session-id-prefix>");
+    }
+    const nameById = new Map(projects.map((p) => [p.id, p.name]));
+    return pickSessionInteractively(candidates.map((session) => ({
+        session,
+        projectName: nameById.get(session.projectId) ?? session.projectId.slice(0, 8),
+    })));
+};
+/**
+ * A real interactive shell in the session's CURRENT workspace — same
+ * /workspace/repo the agent is editing, same dependencies, same network. Not
+ * a shell in the host checkout. The shell holds a workspace lease, so the
+ * container survives the agent settling while the shell lives.
+ */
+const shellCommand = async (config, args) => {
+    const prefix = args.find((a) => !a.startsWith("--"));
+    const session = await resolveLiveSession(config, prefix);
+    say(`${green("✓")} shell in ${session.harness} session ${dim(session.id.slice(0, 8))} · ${dim(session.branch)}${detachHint()}`);
+    const shellProcess = await withSpinner("opening a shell in the session workspace…", api(config, "POST", `/sessions/${session.id}/shell`));
+    say("");
+    const outcome = await attachTty(config, session.id, "shell", 0n, shellProcess.id);
+    if (outcome === "unavailable") {
+        return fail(`tty attach unavailable: could not connect to ${config.url}`);
+    }
     say("");
-    say(`${green("✓")} session settled`);
+    if (outcome === "detached") {
+        say(`${amber("detached")} — the shell keeps running and holds the workspace open`);
+        process.exit(0);
+    }
+    say(`${green("✓")} shell ended`);
     process.exit(0);
 };
+const serviceUrl = (config, service) => {
+    const host = new URL(config.url).hostname || "localhost";
+    // A UDP Service has no page to open — the endpoint is the whole fact.
+    return service.protocol === "udp"
+        ? `${host}:${service.hostPort ?? "?"} (udp)`
+        : `http://${host}:${service.hostPort ?? "?"}`;
+};
+const printService = (config, service) => {
+    const status = service.status === "reachable" ? green(service.status) : amber(service.status);
+    say(`${(service.label ?? service.id.slice(0, 8)).padEnd(12)}  ${dim(`:${service.workspacePort ?? "?"}${service.protocol === "udp" ? "/udp" : ""} →`)} ${serviceUrl(config, service)}  ${status}  ${dim(service.id.slice(0, 8))}`);
+};
+/**
+ * Adopt an already-listening workspace port as a Service: Mend binds a host
+ * port on its private interfaces and pumps every connection into the
+ * session's workspace. No supervision — reachability is the observation.
+ */
+const serviceAdd = async (config, args) => {
+    const nameFlag = args.indexOf("--name");
+    const name = nameFlag !== -1 && args[nameFlag + 1] !== undefined ? String(args[nameFlag + 1]) : null;
+    const protocol = args.includes("--udp") ? "udp" : "tcp";
+    const positional = args.filter((a, i) => !a.startsWith("--") && (nameFlag === -1 || i !== nameFlag + 1));
+    const portRaw = positional.find((a) => /^\d+$/.test(a));
+    if (portRaw === undefined) {
+        return fail("usage: mend service add [session] <port> [--name <n>] [--udp]");
+    }
+    const port = Number(portRaw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return fail(`"${portRaw}" is not a port`);
+    }
+    const prefix = positional.find((a) => a !== portRaw);
+    const session = await resolveLiveSession(config, prefix);
+    const service = await api(config, "POST", `/sessions/${session.id}/services`, {
+        port,
+        name,
+        protocol,
+    });
+    say(`${green("✓")} Service ${service.label ?? ""} · ${service.status}`);
+    say(`  ${cobalt(serviceUrl(config, service))}`);
+    if (protocol === "udp") {
+        say(dim(`  udp — a reply is the only reachability signal; silence just relays`));
+    }
+    else if (service.status !== "reachable") {
+        say(dim(`  nothing answered on :${port} yet — the URL goes live when something listens`));
+    }
+};
+const serviceList = async (config) => {
+    const services = await api(config, "GET", "/services");
+    if (services.length === 0) {
+        say(dim("no live services — mend service add <port> adopts a listening one"));
+        return;
+    }
+    for (const service of services)
+        printService(config, service);
+};
+const serviceStop = async (config, args) => {
+    const needle = args.find((a) => !a.startsWith("--"));
+    if (needle === undefined)
+        return fail("usage: mend service stop <name-or-id-prefix>");
+    const services = await api(config, "GET", "/services");
+    const matches = services.filter((service) => service.label === needle || service.id.startsWith(needle));
+    if (matches.length === 0)
+        return fail(`no live service matches "${needle}"`);
+    const match = matches[0];
+    if (matches.length > 1 || match === undefined) {
+        return fail(`"${needle}" is ambiguous — use more of the id`);
+    }
+    const stoppedService = await api(config, "POST", `/services/${match.id}/stop`);
+    say(`${green("✓")} stopped · ${stoppedService.label ?? stoppedService.id.slice(0, 8)}`);
+};
+const findLiveService = async (config, needle) => {
+    const services = await api(config, "GET", "/services");
+    const matches = services.filter((service) => service.label === needle || service.id.startsWith(needle));
+    if (matches.length === 0)
+        return fail(`no live service matches "${needle}"`);
+    const match = matches[0];
+    if (matches.length > 1 || match === undefined) {
+        return fail(`"${needle}" is ambiguous — use more of the id`);
+    }
+    return match;
+};
+/**
+ * Start and supervise a Service: the command runs as its own PTY process in
+ * the session's workspace (own record = its logs), Mend waits for the
+ * declared port to answer, then exposes it like any Service. The command
+ * never occupies the agent's terminal or a tool call.
+ */
+const serviceRun = async (config, args) => {
+    const dashdash = args.indexOf("--");
+    const usage = "usage: mend service run [session] --port <port> [--name <n>] [--udp] -- <command...>\n" +
+        "       mend service run [session] <name>          (a declared recipe)";
+    // No explicit command = a DECLARED Service: resolve the name against the
+    // session worktree's mend.toml and start (or adopt) its recipe.
+    if (dashdash === -1) {
+        const positionals = args.filter((a) => !a.startsWith("--"));
+        const name = positionals.at(-1);
+        if (name === undefined)
+            return fail(usage);
+        const prefix = positionals.length > 1 ? positionals[0] : undefined;
+        const session = await resolveLiveSession(config, prefix);
+        const recipes = await api(config, "GET", `/sessions/${session.id}/recipes`);
+        const recipe = recipes.find((entry) => entry.name === name);
+        if (recipe === undefined) {
+            const known = recipes.map((entry) => entry.name).join(", ");
+            return fail(recipes.length === 0
+                ? `no mend.toml recipes in this worktree — declare [service.${name}] first`
+                : `no recipe named "${name}" — declared: ${known}`);
+        }
+        if (recipe.command === null) {
+            // A port-only recipe is an adopt: something else starts the listener.
+            const service = await api(config, "POST", `/sessions/${session.id}/services`, {
+                port: recipe.port,
+                name: recipe.name,
+                protocol: recipe.protocol,
+            });
+            say(`${green("✓")} Service ${service.label ?? ""} · ${service.status}`);
+            say(`  ${cobalt(serviceUrl(config, service))}`);
+            return;
+        }
+        const service = await withSpinner(recipe.protocol === "udp"
+            ? `starting ${recipe.name} (udp :${recipe.port})…`
+            : `starting ${recipe.name} — waiting for :${recipe.port} to answer…`, api(config, "POST", `/sessions/${session.id}/services/run`, {
+            argv: ["sh", "-c", recipe.command],
+            port: recipe.port,
+            name: recipe.name,
+            protocol: recipe.protocol,
+        }));
+        say(`${green("✓")} Service ${service.label ?? ""} · ${service.status}`);
+        say(`  ${cobalt(serviceUrl(config, service))}`);
+        say(dim(`  logs: mend service logs ${service.label ?? service.id.slice(0, 8)}`));
+        return;
+    }
+    const argv = args.slice(dashdash + 1);
+    if (argv.length === 0)
+        return fail(usage);
+    const head = args.slice(0, dashdash);
+    const portFlag = head.indexOf("--port");
+    const port = portFlag !== -1 ? Number(head[portFlag + 1]) : Number.NaN;
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return fail(usage);
+    const nameFlag = head.indexOf("--name");
+    const name = nameFlag !== -1 && head[nameFlag + 1] !== undefined ? String(head[nameFlag + 1]) : null;
+    const protocol = head.includes("--udp") ? "udp" : "tcp";
+    const prefix = head.find((a, i) => !a.startsWith("--") && i !== portFlag + 1 && i !== nameFlag + 1);
+    const session = await resolveLiveSession(config, prefix);
+    const service = await withSpinner(protocol === "udp"
+        ? `starting ${name ?? argv[0]} (udp :${port})…`
+        : `starting ${name ?? argv[0]} — waiting for :${port} to answer…`, api(config, "POST", `/sessions/${session.id}/services/run`, {
+        argv,
+        port,
+        name,
+        protocol,
+    }));
+    say(`${green("✓")} Service ${service.label ?? ""} · ${service.status}`);
+    say(`  ${cobalt(serviceUrl(config, service))}`);
+    say(dim(`  logs: mend service logs ${service.label ?? service.id.slice(0, 8)}`));
+};
+/**
+ * Watch a supervised Service's output: record replay, then live tail. A DEAD
+ * Service still answers — its record outlives the process — printed once
+ * instead of followed.
+ */
+const serviceLogs = async (config, args) => {
+    const needle = args.find((a) => !a.startsWith("--"));
+    if (needle === undefined)
+        return fail("usage: mend service logs <name-or-id-prefix>");
+    const everything = await api(config, "GET", "/services?all=1");
+    const matches = everything.filter((service) => service.label === needle || service.id.startsWith(needle));
+    if (matches.length === 0)
+        return fail(`no service matches "${needle}"`);
+    // Prefer the live one; otherwise the newest ended one (list is newest-first).
+    const service = matches.find((m) => m.status !== "exited" && m.status !== "stopped") ?? matches[0];
+    if (service === undefined)
+        return fail(`no service matches "${needle}"`);
+    if (service.sealantSessionId === null) {
+        return fail(`"${needle}" is an adopted port — no process of Mend's, no logs. mend service run supervises.`);
+    }
+    if (service.status === "exited" || service.status === "stopped") {
+        // Post-mortem: print the record, don't attach.
+        const output = await api(config, "GET", `/processes/${service.id}/output`);
+        say(dim(`${service.label ?? service.id.slice(0, 8)} · ${service.status} — recorded output:`));
+        say("");
+        process.stdout.write(output.text.endsWith("\n") ? output.text : `${output.text}\n`);
+        process.exit(0);
+    }
+    say(dim(`following ${service.label ?? service.id.slice(0, 8)} — Ctrl+C detaches, the service keeps running`));
+    say("");
+    const outcome = await attachTty(config, service.sessionId, "service", 0n, service.id, {
+        readOnly: true,
+    });
+    if (outcome === "unavailable") {
+        return fail(`tty attach unavailable: could not connect to ${config.url}`);
+    }
+    say("");
+    say(dim("stream ended"));
+    process.exit(0);
+};
+const serviceRestart = async (config, args) => {
+    const needle = args.find((a) => !a.startsWith("--"));
+    if (needle === undefined)
+        return fail("usage: mend service restart <name-or-id-prefix>");
+    const service = await findLiveService(config, needle);
+    const restarted = await withSpinner(`restarting ${service.label ?? service.id.slice(0, 8)}…`, api(config, "POST", `/services/${service.id}/restart`));
+    say(`${green("✓")} restarted · ${restarted.status}`);
+    say(`  ${cobalt(serviceUrl(config, restarted))}`);
+};
+/**
+ * Scaffold mend.toml from the project's own manifests. Static suggestion,
+ * not detection: package.json scripts and compose port mappings become
+ * recipe proposals the user confirms and commits. Nothing runs.
+ */
+const serviceInit = async (args) => {
+    const root = gitTopLevel(process.cwd()) ?? process.cwd();
+    const target = path.join(root, "mend.toml");
+    if (fs.existsSync(target)) {
+        return fail(`${target} already exists — edit it directly (init never merges)`);
+    }
+    const rootFiles = fs.readdirSync(root);
+    const proposals = [];
+    const readRoot = (name) => fs.readFileSync(path.join(root, name), "utf8");
+    if (rootFiles.includes("package.json")) {
+        proposals.push(...proposeFromPackageJson(readRoot("package.json"), rootFiles));
+    }
+    // Monorepo sweep: every workspace package, named after its folder.
+    const globs = workspaceGlobs(rootFiles.includes("pnpm-workspace.yaml") ? readRoot("pnpm-workspace.yaml") : null, rootFiles.includes("package.json") ? readRoot("package.json") : null);
+    for (const glob of globs) {
+        const parent = glob.replace(/\/?\*+$/, "");
+        const dirs = glob.endsWith("*")
+            ? fs.existsSync(path.join(root, parent))
+                ? fs.readdirSync(path.join(root, parent)).map((dir) => path.join(parent, dir))
+                : []
+            : [glob];
+        for (const dir of dirs) {
+            const manifest = path.join(root, dir, "package.json");
+            if (!fs.existsSync(manifest))
+                continue;
+            for (const proposal of proposeFromWorkspacePackage(path.basename(dir), fs.readFileSync(manifest, "utf8"), rootFiles)) {
+                if (!proposals.some((existing) => existing.name === proposal.name)) {
+                    proposals.push(proposal);
+                }
+            }
+        }
+    }
+    // Every compose flavor in the root, aggregated; non-default files need -f.
+    for (const composeName of rootFiles.filter(isComposeFile).toSorted()) {
+        const isDefault = composeName === "compose.yaml" || composeName === "docker-compose.yml";
+        for (const proposal of proposeFromCompose(readRoot(composeName))) {
+            if (!proposals.some((existing) => existing.name === proposal.name)) {
+                proposals.push({
+                    ...proposal,
+                    command: isDefault
+                        ? proposal.command
+                        : proposal.command.replace("docker compose ", `docker compose -f ${composeName} `),
+                    source: `${composeName}: ${proposal.source}`,
+                });
+            }
+        }
+    }
+    if (proposals.length === 0) {
+        return fail("nothing to propose — no server-ish package.json script with a nameable port, no compose ports");
+    }
+    const toml = renderMendToml(proposals);
+    say(dim(`proposed ${target}:`));
+    say("");
+    process.stdout.write(toml);
+    say("");
+    if (!args.includes("--yes")) {
+        if (process.stdin.isTTY !== true) {
+            return fail("non-interactive — pass --yes to write the file");
+        }
+        const readline = await import("node:readline/promises");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question("write it? [y/N] ");
+        rl.close();
+        if (answer.trim().toLowerCase() !== "y") {
+            say(dim("nothing written"));
+            return;
+        }
+    }
+    fs.writeFileSync(target, toml);
+    say(`${green("✓")} wrote ${target} — commit it, then: mend service run ${proposals[0]?.name}`);
+};
+const serviceCommand = async (config, args) => {
+    const [verb, ...rest] = args;
+    switch (verb) {
+        case "run":
+            return serviceRun(config, rest);
+        case "add":
+            return serviceAdd(config, rest);
+        case "init":
+            return serviceInit(rest);
+        case "list":
+        case undefined:
+            return serviceList(config);
+        case "logs":
+            return serviceLogs(config, rest);
+        case "restart":
+            return serviceRestart(config, rest);
+        case "stop":
+            return serviceStop(config, rest);
+        default:
+            // Sugar: `mend service mysql` reads as `mend service run mysql` — a
+            // bare word that isn't a verb is a recipe name. A miss still explains
+            // itself (declared recipes are listed in the failure).
+            return serviceRun(config, [verb, ...rest]);
+    }
+};
+// ─── keys: the machine's Mend deploy key (docs/GIT-ACCESS.md) ───────────────
+/** Print the public key with the one instruction that makes it useful. */
+const printGitKey = (key) => {
+    if (key.publicKey === null)
+        return;
+    say(key.publicKey);
+    if (key.fingerprint !== null)
+        say(dim(`  ${key.fingerprint}`));
+    say(dim("  add this as a deploy key on your git host (GitHub/GitLab/Gitea: repo"));
+    say(dim("  settings → deploy keys; grant write access if sessions should push),"));
+    say(dim("  then adopt with: mend adopt <ssh-url> --auth mend-key"));
+};
+const keysShow = async (config) => {
+    const key = await api(config, "GET", "/keys/git");
+    if (!key.exists) {
+        say(`no Mend key yet ${dim("— mend keys init generates one (ed25519, stays on the server host)")}`);
+        return;
+    }
+    printGitKey(key);
+};
+const keysInit = async (config) => {
+    const key = await api(config, "POST", "/keys/git");
+    say(`${green("✓")} Mend key ready ${dim("(private half stays on the server host)")}`);
+    printGitKey(key);
+};
+/**
+ * The ssh-agent bridge, client half (docs/GIT-ACCESS.md decision 2): relay
+ * the LOCAL ssh-agent to the Mend server over one standing WebSocket, so
+ * bridge-mode git ops sign with a key that never leaves this machine — a
+ * hardware key blinks here, not on the server. Agent-protocol messages are
+ * relayed verbatim (length-prefixed frames, base64 over JSON); the only
+ * inspection is each message's type byte, to say what is being asked.
+ */
+const keysShare = async (config) => {
+    const agentSock = process.env["SSH_AUTH_SOCK"];
+    if (agentSock === undefined || agentSock === "") {
+        return fail("SSH_AUTH_SOCK is not set — start (or plug in) your ssh-agent first");
+    }
+    const url = new URL(`${config.url}/api/keys/bridge/ws`);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("host", os.hostname());
+    if (config.token !== null)
+        url.searchParams.set("token", config.token);
+    /**
+     * One complete agent exchange against the local agent: fresh connection,
+     * write the framed request verbatim, read one framed response. A hardware
+     * key blocks here until the touch — hence the generous timeout.
+     */
+    const askLocalAgent = (payload) => new Promise((resolve, reject) => {
+        const connection = net.connect(agentSock, () => {
+            connection.write(payload);
+        });
+        const timer = setTimeout(() => {
+            connection.destroy();
+            reject(new Error("the agent did not answer within 60s — touch missed?"));
+        }, 60_000);
+        let pending = Buffer.alloc(0);
+        connection.on("data", (chunk) => {
+            pending = Buffer.concat([pending, chunk]);
+            if (pending.length >= 4 && pending.length >= 4 + pending.readUInt32BE(0)) {
+                clearTimeout(timer);
+                connection.end();
+                resolve(pending.subarray(0, 4 + pending.readUInt32BE(0)));
+            }
+        });
+        connection.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+    // Strictly one request at a time, in arrival order — the agent protocol is
+    // request/response and a hardware key cannot answer two touches at once.
+    let chain = Promise.resolve();
+    const SSH_AGENTC_SIGN_REQUEST = 13;
+    const SSH_AGENTC_REQUEST_IDENTITIES = 11;
+    let attempt = 0;
+    for (;;) {
+        const ws = new WebSocket(url);
+        const closed = new Promise((resolve) => {
+            ws.addEventListener("close", () => resolve(), { once: true });
+        });
+        const opened = await new Promise((resolve) => {
+            ws.addEventListener("open", () => resolve(true), { once: true });
+            ws.addEventListener("error", () => resolve(false), { once: true });
+        });
+        if (opened) {
+            attempt = 0;
+            say(`${green("●")} sharing this machine's ssh-agent with ${config.url}`);
+            say(dim(`  agent: ${agentSock} · signature requests print here · Ctrl-C stops sharing`));
+            ws.addEventListener("message", (event) => {
+                const text = typeof event.data === "string"
+                    ? event.data
+                    : Buffer.from(event.data).toString("utf8");
+                let frame;
+                try {
+                    frame = JSON.parse(text);
+                }
+                catch {
+                    return;
+                }
+                if (frame.t !== "req" ||
+                    typeof frame.id !== "number" ||
+                    typeof frame.payload !== "string") {
+                    return;
+                }
+                const id = frame.id;
+                const payload = Buffer.from(frame.payload, "base64");
+                const type = payload[4];
+                const context = typeof frame.context === "string" ? frame.context : "mend";
+                chain = chain.then(async () => {
+                    const started = Date.now();
+                    if (type === SSH_AGENTC_SIGN_REQUEST) {
+                        say(`${amber("✎")} signature requested by mend ${dim(`(${context})`)}`);
+                        say(dim("  waiting — touch your key if it blinks (up to 60s)…"));
+                    }
+                    else if (type === SSH_AGENTC_REQUEST_IDENTITIES) {
+                        say(dim(`  identities requested (${context})`));
+                    }
+                    try {
+                        const response = await askLocalAgent(payload);
+                        if (ws.readyState !== WebSocket.OPEN)
+                            return null;
+                        ws.send(JSON.stringify({ t: "res", id, payload: response.toString("base64") }));
+                        if (type === SSH_AGENTC_SIGN_REQUEST) {
+                            say(`${green("✓")} signed ${dim(`(${((Date.now() - started) / 1000).toFixed(1)}s)`)}`);
+                        }
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        if (ws.readyState === WebSocket.OPEN) {
+                            ws.send(JSON.stringify({ t: "err", id, message }));
+                        }
+                        if (type === SSH_AGENTC_SIGN_REQUEST)
+                            say(`${amber("✗")} not signed — ${message}`);
+                    }
+                    return null;
+                });
+            });
+        }
+        await closed;
+        attempt += 1;
+        const delay = Math.min(30_000, 1000 * 2 ** Math.min(attempt - 1, 5));
+        say(dim(`not connected — retrying in ${Math.round(delay / 1000)}s (Ctrl-C stops)`));
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+};
+const keysCommand = async (config, args) => {
+    const [verb] = args;
+    switch (verb) {
+        case "init":
+            return keysInit(config);
+        case "share":
+            return keysShare(config);
+        case "show":
+        case undefined:
+            return keysShow(config);
+        default:
+            return fail(`unknown keys command "${verb}" — try: mend keys init | show | share`);
+    }
+};
+const formatDotfileBytes = (bytes) => bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+const dotfilesShow = async (config) => {
+    const dotfiles = await api(config, "GET", "/dotfiles");
+    if (dotfiles.repository === null) {
+        say(`repo      ${dim("none")}`);
+    }
+    else {
+        const branch = dotfiles.repository.ref ?? "default branch";
+        const bootstrap = dotfiles.repository.bootstrap ? "install.sh on" : "install.sh off";
+        say(`repo      ${dotfiles.repository.url} ${dim(`(${branch} · ${bootstrap})`)}`);
+    }
+    if (dotfiles.snapshot === null) {
+        say(`snapshot  ${dim("none — sync from this machine: mend dotfiles sync --all")}`);
+        return;
+    }
+    const snapshot = dotfiles.snapshot;
+    say(`snapshot  ${snapshot.files.length} file${snapshot.files.length === 1 ? "" : "s"} · from ${snapshot.source} · ${dim(snapshot.sha.slice(0, 7))}`);
+    for (const file of snapshot.files) {
+        say(`  ${file.path.padEnd(36)} ${dim(formatDotfileBytes(file.bytes))}`);
+    }
+};
+/**
+ * `mend dotfiles sync` — capture home files ON THIS MACHINE and stream them into the server's
+ * per-user dotfiles store. This is the whole point of the store: the server may be a VPS whose
+ * home directory belongs to a service account, so contents are read here, where they live.
+ */
+const dotfilesSync = async (config, args) => {
+    const all = args.includes("--all");
+    const requestedPaths = args.filter((arg) => !arg.startsWith("--"));
+    const home = os.homedir();
+    if (!all && requestedPaths.length === 0) {
+        const found = scanDotfileCandidates(home);
+        if (found.length === 0) {
+            say(dim("no known config files found under ~"));
+            return;
+        }
+        let group = "";
+        for (const entry of found) {
+            if (entry.group !== group) {
+                group = entry.group;
+                say(dim(group));
+            }
+            say(`  ${entry.path.padEnd(36)} ${dim(formatDotfileBytes(entry.bytes))}`);
+        }
+        say("");
+        say(`sync everything with ${cobalt("mend dotfiles sync --all")}, or pick: ${cobalt("mend dotfiles sync .zshrc .gitconfig")}`);
+        return;
+    }
+    const selected = all ? scanDotfileCandidates(home).map((entry) => entry.path) : requestedPaths;
+    if (selected.length === 0)
+        return fail("nothing to sync — no known config files found under ~");
+    const read = readSyncFiles(home, selected);
+    if ("error" in read)
+        return fail(read.error);
+    const result = await api(config, "POST", "/dotfiles/snapshot", {
+        files: read.files,
+        source: os.hostname(),
+        merge: false,
+    });
+    const snapshot = result.snapshot;
+    if (snapshot === null)
+        return fail("the server accepted the sync but reports no snapshot");
+    say(`${green("synced")} ${snapshot.files.length} file${snapshot.files.length === 1 ? "" : "s"} from ${os.hostname()} · ${dim(snapshot.sha.slice(0, 7))} ${dim("— applies from the next session launch")}`);
+};
+const dotfilesCommand = async (config, args) => {
+    const [verb, ...rest] = args;
+    switch (verb) {
+        case "sync":
+            return dotfilesSync(config, rest);
+        case "show":
+        case undefined:
+            return dotfilesShow(config);
+        default:
+            return fail(`unknown dotfiles command "${verb}" — try: mend dotfiles sync | show`);
+    }
+};
+// ─── completions: live sessions under TAB ───────────────────────────────────
+/**
+ * The data half of shell completion: one live session per line as
+ * `id<TAB>description`. Scripts adapt the shape (zsh wants `id:desc`, bash
+ * wants bare ids). Never fails — a dead server just completes nothing.
+ */
+const completeCommand = async (config, args) => {
+    if (args[0] !== "session")
+        return;
+    try {
+        const [sessions, projects] = await Promise.all([
+            request(config, "GET", "/sessions"),
+            request(config, "GET", "/projects"),
+        ]);
+        const nameById = new Map(projects.map((p) => [p.id, p.name]));
+        for (const session of sessions) {
+            const project = nameById.get(session.projectId) ?? "";
+            process.stdout.write(`${session.id}\t${session.harness} · ${project} · ${session.branch}\n`);
+        }
+    }
+    catch {
+        // Completion must never surface an error into the user's TAB press.
+    }
+};
+const ZSH_COMPLETIONS = `#compdef mend
+_mend() {
+  local -a commands
+  commands=(
+    'adopt:adopt a repository into the store'
+    'codex:new session + codex' 'claude:new session + claude' 'opencode:new session + opencode'
+    'run:new session + arbitrary command'
+    'attach:reattach to a running session' 'shell:open a shell in a live session workspace'
+    'service:reachable ports — add, list, stop'
+    'keys:the machine Mend deploy key — init, show, share'
+    'continue:resume with the pending follow-up' 'resume:rejoin a settled session'
+    'rejoin:attach if live, otherwise resume'
+    'projects:adopted projects' 'sessions:sessions with review facts' 'status:active sessions'
+    'ui:the dashboard' 'help:help'
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+  case $words[2] in
+    shell|attach|continue|resume|rejoin)
+      local -a sessions
+      sessions=(\${(f)"$(command mend __complete session 2>/dev/null | tr '\\t' ':')"})
+      (( \${#sessions} )) && _describe 'session' sessions
+      ;;
+  esac
+}
+_mend "$@"
+`;
+const BASH_COMPLETIONS = `_mend() {
+  local cur=\${COMP_WORDS[COMP_CWORD]}
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "adopt codex claude opencode run attach shell service keys continue resume rejoin projects sessions status ui help" -- "$cur") )
+    return
+  fi
+  case \${COMP_WORDS[1]} in
+    shell|attach|continue|resume|rejoin)
+      COMPREPLY=( $(compgen -W "$(command mend __complete session 2>/dev/null | cut -f1)" -- "$cur") )
+      ;;
+  esac
+}
+complete -F _mend mend
+`;
+/** Print the hook for the named shell; the user wires it into their rc file. */
+const completionsCommand = (args) => {
+    switch (args[0]) {
+        case "zsh":
+            process.stdout.write(ZSH_COMPLETIONS);
+            return;
+        case "bash":
+            process.stdout.write(BASH_COMPLETIONS);
+            return;
+        default:
+            return fail('usage: mend completions zsh|bash — e.g. mend completions zsh > "$fpath[1]/_mend"');
+    }
+};
 // ─── supervised run: platform workspace + PTY + record ──────────────────────
 const supervisedRun = async (config, session, argv) => {
     const launched = await withSpinner("provisioning workspace — a first launch builds the harness image (can take minutes)…", api(config, "POST", `/sessions/${session.id}/launch`, { argv }));
@@ -299,12 +1141,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 +1200,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,39 +1233,273 @@ 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 adopt [source] [--name <name>]   adopt a repository into the store (default: cwd)
+  mend                                  the dashboard: every project and session, live
+  mend adopt [source] [--name <name>] [--auth ambient|mend-key|bridge]
+                                        adopt a repository into the store (default: cwd; any git
+                                        URL — GitHub, GitLab, self-hosted, ssh://, a local path)
+  mend keys init                        generate the machine's Mend deploy key (ed25519)
+  mend keys show                        print the public key — add it as a deploy key on your git host
+  mend dotfiles                         your dotfiles on the server: repo + synced home files
+  mend dotfiles sync [--all | paths…]   capture config files from THIS machine into your store
+  mend keys share                       relay THIS machine's ssh-agent to the server (bridge mode:
+                                        hardware keys sign here; Ctrl-C stops sharing)
   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 shell [session-id-prefix]        open a shell in a live session's workspace
+  mend service run [session] --port <p> [--name <n>] [--udp] -- <command...>
+                                        start + supervise a server in the session workspace
+  mend service run [session] <name>     start a declared Service (mend.toml recipe)
+  mend service <name>                   shorthand for the above
+  mend service init [--yes]             scaffold mend.toml from package.json + compose ports
+  mend service add [session] <port> [--name <n>] [--udp]
+                                        adopt a listening workspace port — reachable on this machine
+  mend service list                     every live service and its observed state
+  mend service logs <name-or-id>        follow a supervised service's output (replay, then live)
+  mend service restart <name-or-id>     re-run its recorded command — same URL
+  mend service stop <name-or-id>        stop a service (closes its host port)
   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)
+  mend completions zsh|bash             print the TAB-completion hook (live session ids under TAB)
 
   server: MEND_URL (default http://localhost:3105) · auth: MEND_TOKEN
-  config file: ~/.mend/cli.json { "url": ..., "token": ... }
+  detach key: Ctrl+] (set MEND_DETACH_KEY=none when an outer multiplexer owns detaching)
+  config file: ~/.config/mend/cli.json { "url": ..., "token": ... }
 `;
 const main = async () => {
     const [command, ...rest] = process.argv.slice(2);
@@ -448,13 +1514,32 @@ const main = async () => {
             return launch(config, command, rest);
         case "attach":
             return attach(config, rest);
+        case "shell":
+            return shellCommand(config, rest);
+        case "service":
+            return serviceCommand(config, rest);
+        case "keys":
+            return keysCommand(config, rest);
+        case "dotfiles":
+            return dotfilesCommand(config, rest);
+        case "completions":
+            return completionsCommand(rest);
+        case "__complete":
+            return completeCommand(config, rest);
         case "continue":
             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);