@sealant/mend 0.20.0 → 0.21.0

package/dist/agent-share.js

@@ -0,0 +1,150 @@
+import * as net from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+/** The bridge endpoint for a server url: ws(s), this machine named, the token as a query. */
+export const bridgeUrlOf = (serverUrl, token, host) => {
+    const url = new URL(`${serverUrl}/api/keys/bridge/ws`);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("host", host);
+    if (token !== null)
+        url.searchParams.set("token", token);
+    return url;
+};
+/** Reconnect backoff: 1s, 2s, … capped at 30s. */
+export const retryDelayMs = (attempt) => Math.min(30_000, 1000 * 2 ** Math.min(Math.max(attempt - 1, 0), 5));
+const SSH_AGENTC_REQUEST_IDENTITIES = 11;
+const SSH_AGENTC_SIGN_REQUEST = 13;
+/**
+ * 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 = (agentSock, 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);
+    });
+});
+/** An abortable wait; an abort simply ends it early. */
+const sleep = (ms, signal) => delay(ms, undefined, { signal }).then(() => undefined, () => undefined);
+/** Share until the signal aborts; every connect, drop, and signature is an event. */
+export const shareAgent = async (options) => {
+    const { url, agentSock, signal, onEvent } = options;
+    // Requests are answered one at a time: the agent protocol has one in flight.
+    let chain = Promise.resolve();
+    let attempt = 0;
+    while (!signal.aborted) {
+        const ws = new WebSocket(url);
+        const onAbort = () => ws.close();
+        signal.addEventListener("abort", onAbort, { once: true });
+        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;
+            onEvent({ kind: "connected" });
+            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)
+                        onEvent({ kind: "sign-requested", context });
+                    else if (type === SSH_AGENTC_REQUEST_IDENTITIES) {
+                        onEvent({ kind: "identities-requested", context });
+                    }
+                    try {
+                        const response = await askLocalAgent(agentSock, 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) {
+                            onEvent({ kind: "signed", context, seconds: (Date.now() - started) / 1000 });
+                        }
+                    }
+                    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)
+                            onEvent({ kind: "not-signed", context, message });
+                    }
+                    return null;
+                });
+            });
+        }
+        await closed;
+        signal.removeEventListener("abort", onAbort);
+        if (signal.aborted)
+            return;
+        attempt += 1;
+        const retryMs = retryDelayMs(attempt);
+        onEvent({ kind: "disconnected", retryMs });
+        await sleep(retryMs, signal);
+    }
+};
+/** Start sharing in the background; `stop` ends it. */
+export const startAgentShare = (options) => {
+    const controller = new AbortController();
+    const listeners = new Set();
+    let state = "connecting";
+    void shareAgent({
+        ...options,
+        signal: controller.signal,
+        onEvent: (event) => {
+            if (event.kind === "connected")
+                state = "connected";
+            else if (event.kind === "disconnected")
+                state = "connecting";
+            for (const listener of listeners)
+                listener(event);
+        },
+    });
+    return {
+        snapshot: () => state,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        stop: () => controller.abort(),
+    };
+};

package/dist/dashboard.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "@opentui/reac
 import { CliRenderEvents, createCliRenderer } from "@opentui/core";
 import { createRoot, useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react";
 import { QueryClient, QueryClientProvider, useMutation, useQuery, useQueryClient, } from "@tanstack/react-query";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { deriveHarnesses, deriveProjects, advanceFromBase, deriveRows, deriveWorktrees, filterBranches, foldGroupStatus, rowKeyOf, worktreeDisplayName, fetchWorkbench, liveProtocolOf, liveShellOf, mapWorkbenchSessions, markSessionStopped, removeWorktreeGroup, prependSession, removeSession, replaceSession, WORKBENCH_KEY, } from "./dashboard-model.js";
 import { reviewTargetForSession } from "./review-workflow.js";
 import { ReviewScreen } from "./review.js";
@@ -124,6 +124,8 @@ const keepSpanVisible = (scroll, top, height) => {
 };
 const keepRowVisible = (scroll, index) => keepSpanVisible(scroll, index, 1);
 const PROJECTS_PANE_WIDTH = 30;
+/** The header's share fact when no share runs. */
+const noShare = () => "off";
 const App = ({ ctx, onQuit }) => {
     const renderer = useRenderer();
     const queryClient = useQueryClient();
@@ -143,6 +145,7 @@ const App = ({ ctx, onQuit }) => {
     const [busy, setBusy] = useState(null);
     const [busyStarted, setBusyStarted] = useState(0);
     const [status, setStatus] = useState(null);
+    const shareState = useSyncExternalStore((onChange) => ctx.agentShare?.subscribe(() => onChange()) ?? (() => { }), ctx.agentShare === null ? noShare : ctx.agentShare.snapshot);
     const [editing, setEditing] = useState(null);
     /** Session id a stop is armed against; the second press fires it. */
     const [stopArmed, setStopArmed] = useState(null);
@@ -197,6 +200,23 @@ const App = ({ ctx, onQuit }) => {
     const selectSession = (id) => setSessionKey(`s:${id}`);
     const say = (text) => setStatus({ text, at: Date.now() });
     const refetch = () => void queryClient.invalidateQueries({ queryKey: WORKBENCH_KEY });
+    // Signature requests are facts from outside React — the status line says them.
+    useEffect(() => {
+        const share = ctx.agentShare;
+        if (share === null)
+            return;
+        return share.subscribe((event) => {
+            if (event === null)
+                return;
+            if (event.kind === "sign-requested") {
+                say(`✎ signature requested (${event.context}) — touch your key if it blinks`);
+            }
+            else if (event.kind === "signed")
+                say(`✓ signed (${event.seconds.toFixed(1)}s)`);
+            else if (event.kind === "not-signed")
+                say(`✗ not signed — ${event.message}`);
+        });
+    }, [ctx.agentShare]);
     // A repo underfoot that the store has never met: raise the adopt offer the
     // first time the workbench answers and no project matches the cwd.
     useEffect(() => {
@@ -1051,7 +1071,7 @@ const App = ({ ctx, onQuit }) => {
                 refetch();
             }, onQuit: onQuit }));
     }
-    return (_jsxs("box", { flexGrow: 1, flexDirection: "column", backgroundColor: "transparent", children: [_jsxs("box", { height: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs("text", { height: 1, bg: "transparent", children: [_jsx("span", { fg: INK, children: " mend" }), _jsxs("span", { fg: MUTED, children: ["  ", projectItems.length, " project", projectItems.length === 1 ? "" : "s"] }), _jsx("span", { fg: FAINT, children: " \u00B7 " }), _jsxs("span", { fg: liveTotal > 0 ? MUTED : FAINT, children: [liveTotal, " live"] })] }), _jsx("text", { height: 1, fg: FAINT, bg: "transparent", children: `${ctx.config.url}  ` })] }), _jsxs("box", { flexGrow: 1, flexShrink: 1, minHeight: 0, flexDirection: "row", children: [showProjectsPane ? (_jsx(Pane, { title: "projects", focused: focus === "projects", width: PROJECTS_PANE_WIDTH, children: _jsxs("scrollbox", { ref: projectScrollRef, flexGrow: 1, flexShrink: 1, minHeight: 0, style: paneScrollStyle, children: [projectItems.map((item, index) => (_jsx(ProjectRow, { item: item, selected: index === projectIndex, nameWidth: nameWidth }, item.project.id))), data !== undefined && projectItems.length === 0 ? (_jsx("text", { height: 1, fg: FAINT, bg: "transparent", children: "  none adopted yet" })) : null] }) })) : null, _jsx(Pane, { title: sessionsTitle, focused: focus === "sessions", grow: true, children: _jsxs("scrollbox", { ref: sessionScrollRef, flexGrow: 1, flexShrink: 1, minHeight: 0, style: paneScrollStyle, children: [rows.map((row, index) => row.kind === "worktree" ? (_jsx(WorktreeHeaderRow, { group: row.group, selected: index === rowIndex }, rowKeyOf(row))) : (_jsx(SessionChildRow, { item: row.item, selected: index === rowIndex }, rowKeyOf(row)))), data !== undefined && rows.length === 0 ? (_jsx("text", { height: 1, fg: FAINT, bg: "transparent", children: "  no sessions yet — n starts one" })) : null, loadFailure !== null ? (_jsx("text", { height: 1, fg: INK_2, bg: "transparent", children: `  ${loadFailure} — retrying` })) : null] }) })] }), picker !== null ? (_jsx(Pane, { title: pickerTitle, focused: true, height: 2 + pickerItems.length, children: pickerItems.map((item, index) => (_jsx(HarnessRow, { item: item, selected: index === pickerIndex }, String(item.harness)))) })) : editing !== null ? (_jsx("box", { border: true, borderStyle: "rounded", borderColor: COBALT, title: ` label — ${editing.harness} ${editing.id.slice(0, 8)} `, titleAlignment: "left", backgroundColor: "transparent", height: 3, flexShrink: 0, children: _jsx("input", { focused: true, value: editing.label ?? "", placeholder: "a few words for what this session is doing (empty clears)", backgroundColor: "transparent", focusedBackgroundColor: "transparent", textColor: INK, focusedTextColor: INK, placeholderColor: FAINT, cursorColor: INK, flexGrow: 1, onSubmit: (value) => {
+    return (_jsxs("box", { flexGrow: 1, flexDirection: "column", backgroundColor: "transparent", children: [_jsxs("box", { height: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs("text", { height: 1, bg: "transparent", children: [_jsx("span", { fg: INK, children: " mend" }), _jsxs("span", { fg: MUTED, children: ["  ", projectItems.length, " project", projectItems.length === 1 ? "" : "s"] }), _jsx("span", { fg: FAINT, children: " \u00B7 " }), _jsxs("span", { fg: liveTotal > 0 ? MUTED : FAINT, children: [liveTotal, " live"] }), shareState === "off" ? null : (_jsxs(_Fragment, { children: [_jsx("span", { fg: FAINT, children: " \u00B7 " }), _jsx("span", { fg: shareState === "connected" ? MUTED : FAINT, children: shareState === "connected" ? "agent shared" : "agent share reconnecting" })] }))] }), _jsx("text", { height: 1, fg: FAINT, bg: "transparent", children: `${ctx.config.url}  ` })] }), _jsxs("box", { flexGrow: 1, flexShrink: 1, minHeight: 0, flexDirection: "row", children: [showProjectsPane ? (_jsx(Pane, { title: "projects", focused: focus === "projects", width: PROJECTS_PANE_WIDTH, children: _jsxs("scrollbox", { ref: projectScrollRef, flexGrow: 1, flexShrink: 1, minHeight: 0, style: paneScrollStyle, children: [projectItems.map((item, index) => (_jsx(ProjectRow, { item: item, selected: index === projectIndex, nameWidth: nameWidth }, item.project.id))), data !== undefined && projectItems.length === 0 ? (_jsx("text", { height: 1, fg: FAINT, bg: "transparent", children: "  none adopted yet" })) : null] }) })) : null, _jsx(Pane, { title: sessionsTitle, focused: focus === "sessions", grow: true, children: _jsxs("scrollbox", { ref: sessionScrollRef, flexGrow: 1, flexShrink: 1, minHeight: 0, style: paneScrollStyle, children: [rows.map((row, index) => row.kind === "worktree" ? (_jsx(WorktreeHeaderRow, { group: row.group, selected: index === rowIndex }, rowKeyOf(row))) : (_jsx(SessionChildRow, { item: row.item, selected: index === rowIndex }, rowKeyOf(row)))), data !== undefined && rows.length === 0 ? (_jsx("text", { height: 1, fg: FAINT, bg: "transparent", children: "  no sessions yet — n starts one" })) : null, loadFailure !== null ? (_jsx("text", { height: 1, fg: INK_2, bg: "transparent", children: `  ${loadFailure} — retrying` })) : null] }) })] }), picker !== null ? (_jsx(Pane, { title: pickerTitle, focused: true, height: 2 + pickerItems.length, children: pickerItems.map((item, index) => (_jsx(HarnessRow, { item: item, selected: index === pickerIndex }, String(item.harness)))) })) : editing !== null ? (_jsx("box", { border: true, borderStyle: "rounded", borderColor: COBALT, title: ` label — ${editing.harness} ${editing.id.slice(0, 8)} `, titleAlignment: "left", backgroundColor: "transparent", height: 3, flexShrink: 0, children: _jsx("input", { focused: true, value: editing.label ?? "", placeholder: "a few words for what this session is doing (empty clears)", backgroundColor: "transparent", focusedBackgroundColor: "transparent", textColor: INK, focusedTextColor: INK, placeholderColor: FAINT, cursorColor: INK, flexGrow: 1, onSubmit: (value) => {
                         if (typeof value === "string")
                             submitRename(editing, value);
                     } }) })) : showDetail ? (_jsx(Pane, { title: detailTitle, focused: false, height: 6, children: _jsx(SessionDetail, { item: selectedSession }) })) : null, adoptOffer !== null ? (_jsxs("box", { position: "absolute", zIndex: 11, left: Math.max(1, Math.floor((terminalCols - Math.min(70, terminalCols - 4)) / 2)), top: Math.max(1, Math.floor((terminalRows - 7) / 2)), width: Math.min(70, terminalCols - 4), height: 7, border: true, borderStyle: "rounded", borderColor: COBALT, title: " adopt this repository? ", titleAlignment: "left", backgroundColor: SURFACE, flexDirection: "column", children: [_jsxs("text", { height: 1, bg: SURFACE, children: [_jsx("span", { children: "  " }), _jsx("span", { fg: INK, children: adoptOffer.name }), _jsx("span", { fg: FAINT, children: " · not in the store yet" })] }), _jsx("text", { height: 1, bg: SURFACE, fg: MUTED, children: `  ${adoptOffer.source}` }), _jsxs("text", { height: 1, bg: SURFACE, children: [_jsx("span", { fg: FAINT, children: "  auth  " }), ADOPT_AUTH_MODES.map((candidate, index) => (_jsxs("span", { children: [index > 0 ? _jsx("span", { fg: FAINT, children: " · " }) : null, _jsx("span", { fg: index === adoptOffer.modeIndex ? COBALT : FAINT, children: index === adoptOffer.modeIndex ? `▸ ${candidate.label}` : candidate.label })] }, candidate.mode)))] }), _jsx("text", { height: 1, bg: SURFACE, fg: FAINT, children: `        ${ADOPT_AUTH_MODES[adoptOffer.modeIndex]?.hint ?? ""}` }), _jsx("text", { height: 1, bg: SURFACE, fg: FAINT, children: adoptOffer.source === adoptOffer.root

package/dist/help.js

@@ -63,11 +63,11 @@ export const COMMANDS = [
         synopsis: ["[source] [--name <name>] [--auth ambient|mend-key|bridge]"],
         description: [
             "Clones the repository into Mend's store. Every session then gets its own worktree of it. The default source is the current directory; any git URL works, GitHub, GitLab, self-hosted, ssh://, or a local path.",
-            "--auth says how the store fetches from the remote. ambient uses the server's own credentials. mend-key uses this machine's deploy key (see mend keys). bridge relays this machine's ssh-agent while mend keys share runs, so hardware keys stay here.",
+            "--auth says how the store fetches from the remote. Default: your mode from mend keys mode. mend-key signs with your Mend key on the server (see mend keys). bridge relays this machine's ssh-agent while a mend command runs here, so hardware keys stay on your desk. ambient uses the server's own credentials.",
         ],
         options: [
             { flag: "--name <name>", text: "the project's name in Mend. Default: the repository's" },
-            { flag: "--auth <mode>", text: "ambient, mend-key, or bridge. Default: ambient" },
+            { flag: "--auth <mode>", text: "mend-key, bridge, or ambient. Default: mend keys mode" },
         ],
         examples: [
             { command: "mend adopt", text: "the repository you are standing in" },
@@ -471,21 +471,33 @@ export const COMMANDS = [
     {
         name: "keys init",
         section: "project setup",
-        summary: "generate this machine's Mend deploy key (ed25519)",
+        summary: "create your Mend key (ed25519) on the server",
         synopsis: [],
         description: [
-            "Creates a key under ~/.config/mend/keys for projects adopted with --auth mend-key. Add the public key on your git host as a deploy key.",
+            "One key per user, held on the server, never copied anywhere. Add the public key to your git account's SSH keys and every repository you can reach works, from detached sessions and the phone too. For one repository only, add it as that repository's deploy key instead.",
         ],
-        see: ["keys show", "adopt"],
+        see: ["keys show", "keys mode", "adopt"],
     },
     {
         name: "keys show",
         section: "project setup",
-        summary: "print the public key",
+        summary: "print your Mend public key",
         synopsis: [],
-        description: ["The key to add as a deploy key on your git host."],
+        description: [
+            "The key to add to your git account's SSH keys, or as a deploy key on one repository.",
+        ],
         see: ["keys init"],
     },
+    {
+        name: "keys mode",
+        section: "project setup",
+        summary: "how your remotes are reached: mend-key or bridge",
+        synopsis: ["[mend-key|bridge]"],
+        description: [
+            "mend-key (the default) signs with your Mend key on the server and works whenever the server is up. bridge signs with this machine's ssh-agent, so a hardware key never leaves your desk, but only while a mend command is running here. New projects adopt with this mode; a project's setup page can override it. Without a value, prints the current mode.",
+        ],
+        see: ["keys init", "keys share"],
+    },
     {
         name: "keys share",
         section: "project setup",
@@ -493,8 +505,9 @@ export const COMMANDS = [
         synopsis: [],
         description: [
             "Bridge mode for projects adopted with --auth bridge: the server's git operations sign with the keys in this machine's ssh-agent, so hardware keys never leave here. Runs until Ctrl-C.",
+            "When your mode is bridge (mend keys mode), every attaching mend command and the dashboard do this on their own for as long as they run, so this command is for a machine that is not running one. The server takes one signer at a time; a newer share replaces the older one.",
         ],
-        see: ["adopt"],
+        see: ["keys mode", "adopt"],
     },
     // ── this machine ───────────────────────────────────────────────────────
     {

package/dist/main.js

@@ -5,6 +5,7 @@ import { createRequire } from "node:module";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
+import { bridgeUrlOf, shareAgent, startAgentShare } from "./agent-share.js";
 import { readClipboardImage } from "./clipboard.js";
 import { doctorCommand } from "./doctor.js";
 import { readSyncFiles, scanDotfileCandidates } from "./dotfiles.js";
@@ -195,7 +196,7 @@ const adopt = async (config, args) => {
     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)")}`);
+        say(`${dim("  git auth")} mend key ${dim("(your Mend key signed this clone)")}`);
     }
     else if (project.gitAuthMode === "bridge") {
         say(`${dim("  git auth")} bridge ${dim("(signed through the connected `mend keys share`)")}`);
@@ -1474,9 +1475,9 @@ const printGitKey = (key) => {
     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"));
+    say(dim("  add this to your git account's SSH keys (GitHub: settings → SSH keys) so"));
+    say(dim("  every repository you can reach works; for one repository only, add it"));
+    say(dim("  as that repository's deploy key instead (grant write if sessions push)"));
 };
 const keysShow = async (config) => {
     const key = await api(config, "GET", "/keys/git");
@@ -1492,125 +1493,73 @@ const keysInit = async (config) => {
     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.
+ * `mend keys share`: the ssh-agent bridge in the foreground (agent-share.ts
+ * holds the relay). Prints every connect, drop, and signature; Ctrl-C stops.
  */
 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 = parseMendUrl(`${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 {
+    const url = bridgeUrlOf(parseMendUrl(config.url).toString().replace(/\/$/, ""), config.token, os.hostname());
+    await shareAgent({
+        url,
+        agentSock,
+        signal: new AbortController().signal,
+        onEvent: (event) => {
+            switch (event.kind) {
+                case "connected":
+                    say(`${green("●")} sharing this machine's ssh-agent with ${config.url}`);
+                    say(dim(`  agent: ${agentSock} · signature requests print here · Ctrl-C stops sharing`));
                     return;
-                }
-                if (frame.t !== "req" ||
-                    typeof frame.id !== "number" ||
-                    typeof frame.payload !== "string") {
+                case "disconnected":
+                    say(dim(`not connected — retrying in ${Math.round(event.retryMs / 1000)}s (Ctrl-C stops)`));
                     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));
+                case "sign-requested":
+                    say(`${amber("✎")} signature requested by mend ${dim(`(${event.context})`)}`);
+                    say(dim("  waiting — touch your key if it blinks (up to 60s)…"));
+                    return;
+                case "identities-requested":
+                    say(dim(`  identities requested (${event.context})`));
+                    return;
+                case "signed":
+                    say(`${green("✓")} signed ${dim(`(${event.seconds.toFixed(1)}s)`)}`);
+                    return;
+                case "not-signed":
+                    say(`${amber("✗")} not signed — ${event.message}`);
+                    return;
+            }
+        },
+    });
+};
+/**
+ * `mend keys mode [mend-key|bridge]`: how this user's remotes are reached by
+ * default. The Mend key lives on the server and works whenever the server
+ * is up — detached sessions, the phone, the hot pool. Bridge signs with this
+ * machine's ssh-agent and only works while a mend command is running here.
+ */
+const keysMode = async (config, args) => {
+    const [value] = args;
+    if (value !== undefined && value !== "mend-key" && value !== "bridge") {
+        return fail(`keys mode takes mend-key or bridge, not "${value}"`);
+    }
+    const access = value === undefined
+        ? await api(config, "GET", "/me/git-access")
+        : await api(config, "PUT", "/me/git-access", { mode: value });
+    if (value !== undefined)
+        say(`${green("✓")} git access · ${value}`);
+    if (access.mode === "mend-key") {
+        say(`mend-key ${dim("— your Mend key on the server signs; works whenever the server is up")}`);
+        if (access.key.exists)
+            printGitKey(access.key);
+        else
+            say(dim("  no key yet — mend keys init creates it"));
+        return;
     }
+    say(`bridge ${dim("— this machine's ssh-agent signs; only while a mend command runs here")}`);
+    say(access.bridge.connected
+        ? `${green("●")} signer connected · ${access.bridge.clientName ?? "unknown machine"}`
+        : dim("  no signer connected — mend shares the agent whenever it runs (or: mend keys share)"));
 };
 const keysCommand = async (config, args) => {
     const [verb] = args;
@@ -1619,6 +1568,8 @@ const keysCommand = async (config, args) => {
             return keysInit(config);
         case "share":
             return keysShare(config);
+        case "mode":
+            return keysMode(config, args.slice(1));
         case "show":
         case undefined:
             return keysShow(config);
@@ -2565,15 +2516,58 @@ const dashboard = async (config) => {
         process.exit(rerun.status ?? 0);
     }
     const { runDashboard } = await import("./dashboard.js");
-    await runDashboard({
-        config,
-        cwd: process.cwd(),
-        cwdBranch: gitCurrentBranch(process.cwd()),
-        api: (method, route, body) => request(config, method, route, body),
-        attachTty: (sessionId, harness, processId) => attachTty(config, sessionId, harness, 0n, processId),
-    });
+    const agentShare = await startShareIfBridge(config);
+    try {
+        await runDashboard({
+            config,
+            cwd: process.cwd(),
+            cwdBranch: gitCurrentBranch(process.cwd()),
+            api: (method, route, body) => request(config, method, route, body),
+            attachTty: (sessionId, harness, processId) => attachTty(config, sessionId, harness, 0n, processId),
+            agentShare,
+        });
+    }
+    finally {
+        agentShare?.stop();
+    }
 };
 // ─── entry ──────────────────────────────────────────────────────────────────
+/**
+ * Share this machine's ssh-agent for as long as the calling command runs —
+ * only when the user's git access is bridge (mend keys mode). Their remotes
+ * then sign here, and a base fetch before a worktree is created can't be
+ * skipped for want of a signer. Any other mode, no agent, or an unreachable
+ * server: nothing is shared. A newer share replaces an older one on the
+ * server, so overlapping mend commands hand over rather than fight.
+ */
+const startShareIfBridge = async (config) => {
+    const agentSock = process.env["SSH_AUTH_SOCK"];
+    if (agentSock === undefined || agentSock === "")
+        return null;
+    let access;
+    try {
+        access = await request(config, "GET", "/me/git-access");
+    }
+    catch {
+        return null;
+    }
+    if (access.mode !== "bridge")
+        return null;
+    return startAgentShare({
+        url: bridgeUrlOf(parseMendUrl(config.url).toString().replace(/\/$/, ""), config.token, os.hostname()),
+        agentSock,
+    });
+};
+/** Run one command under the share (see startShareIfBridge); stop it on the way out. */
+const withAgentShare = async (config, work) => {
+    const share = await startShareIfBridge(config);
+    try {
+        return await work();
+    }
+    finally {
+        share?.stop();
+    }
+};
 /** `mend help [command...]`: the index, a group, or one page. */
 const helpCommand = (words) => {
     if (words.length === 0) {
@@ -2630,13 +2624,13 @@ const main = async () => {
         case "claude":
         case "opencode":
         case "run":
-            return launch(config, command, rest);
+            return withAgentShare(config, () => launch(config, command, rest));
         case "attach":
-            return attach(config, rest);
+            return withAgentShare(config, () => attach(config, rest));
         case "stop":
             return stopCommand(config, rest);
         case "shell":
-            return shellCommand(config, rest);
+            return withAgentShare(config, () => shellCommand(config, rest));
         case "service":
             return serviceCommand(config, rest);
         case "login":
@@ -2671,9 +2665,9 @@ const main = async () => {
         case "continue":
             return continueSession(config, rest);
         case "resume":
-            return resumeCommand(config, rest);
+            return withAgentShare(config, () => resumeCommand(config, rest));
         case "rejoin":
-            return rejoinCommand(config, rest);
+            return withAgentShare(config, () => rejoinCommand(config, rest));
         case "projects":
             return projectsCommand(config);
         case "refresh":

package/dist/shared.js

@@ -161,17 +161,7 @@ export const parseLaunchArgs = (args) => {
 export const isDetachChunk = (data) => {
     if (data.includes(0x1d))
         return true;
-    // latin1 maps bytes 1:1, so the scan sees exactly the wire bytes. A string
-    // scan rather than a regex: an escape byte inside a pattern trips lint, and
-    // anchoring on the real ESC[ prefix keeps pasted text from ever matching.
-    const text = data.toString("latin1");
-    const prefix = "\u001b[93;5";
-    for (let start = text.indexOf(prefix); start !== -1; start = text.indexOf(prefix, start + 1)) {
-        const rest = text.slice(start + prefix.length);
-        if (rest.startsWith("u") || rest.startsWith(":1u") || rest.startsWith(":2u"))
-            return true;
-    }
-    return false;
+    return csiUKeysOf(data).some((key) => key.code === 93 && isCtrlChord(key) && isPressOrRepeat(key));
 };
 /**
  * What to call a session's worktree in banners and rows: a NAMED worktree is
@@ -293,16 +283,43 @@ export const normalizeProjectName = (raw) => {
         .replace(/-+$/, "");
     return slug === "" ? "project" : slug.slice(0, 64);
 };
+// Built from a string: an escape byte inside a regex literal trips lint.
+const CSI_U = new RegExp(`${String.fromCharCode(0x1b)}\\[(\\d+)(?::\\d*)*(?:;(\\d+)(?::(\\d+))?)?(?:;[\\d:]+)?u`, "g");
+const LOCK_MODIFIERS = 64 | 128;
+/** Every CSI-u key report inside a chunk, in order. */
+export const csiUKeysOf = (data) => {
+    // latin1 maps bytes 1:1, so the scan sees exactly the wire bytes.
+    const text = data.toString("latin1");
+    const keys = [];
+    for (const match of text.matchAll(CSI_U)) {
+        const code = Number(match[1]);
+        const mods = (match[2] === undefined ? 1 : Number(match[2])) - 1;
+        const event = match[3] === undefined ? 1 : Number(match[3]);
+        keys.push({ code, mods: mods & ~LOCK_MODIFIERS, event });
+    }
+    return keys;
+};
+const CTRL = 4;
+const SHIFT = 1;
+/** Ctrl held, optionally shift, nothing else (alt/super/hyper/meta make it another chord). */
+const isCtrlChord = (key) => (key.mods & ~SHIFT) === CTRL;
+const isPressOrRepeat = (key) => key.event === 1 || key.event === 2;
 /**
- * Whether one stdin chunk is exactly Ctrl+V — the raw 0x16 byte, or the
- * kitty CSI-u form `ESC [ 118 ; 5 u` (`v` is code 118) on press or repeat.
- * Exact, not contained: a paste that happens to carry 0x16 is not a request.
+ * Whether one stdin chunk is Ctrl+V — the raw 0x16 byte on its own, or one
+ * CSI-u report of `v` (118) or `V` (86) with ctrl, on press or repeat. Exact
+ * for the raw byte: a paste that happens to carry 0x16 is not a request.
  */
 export const isPasteChunk = (data) => {
     if (data.length === 1 && data[0] === 0x16)
         return true;
-    const text = data.toString("latin1");
-    return text === "\u001b[118;5u" || text === "\u001b[118;5:1u" || text === "\u001b[118;5:2u";
+    const keys = csiUKeysOf(data);
+    const key = keys[0];
+    return (keys.length === 1 &&
+        key !== undefined &&
+        (key.code === 118 || key.code === 86) &&
+        isCtrlChord(key) &&
+        isPressOrRepeat(key) &&
+        data.toString("latin1").startsWith("\u001b["));
 };
 /**
  * Follow the remote app's bracketed-paste mode through the bytes it writes:

package/man/mend-accounts.1

@@ -1,4 +1,4 @@
-.TH MEND-ACCOUNTS 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-ACCOUNTS 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-accounts \- your connected accounts on the platform
 .SH SYNOPSIS

package/man/mend-adopt.1

@@ -1,4 +1,4 @@
-.TH MEND-ADOPT 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-ADOPT 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-adopt \- adopt a repository into the store
 .SH SYNOPSIS
@@ -8,14 +8,14 @@ mend\-adopt \- adopt a repository into the store
 .PP
 Clones the repository into Mend's store. Every session then gets its own worktree of it. The default source is the current directory; any git URL works, GitHub, GitLab, self\-hosted, ssh://, or a local path.
 .PP
-\-\-auth says how the store fetches from the remote. ambient uses the server's own credentials. mend\-key uses this machine's deploy key (see mend keys). bridge relays this machine's ssh\-agent while mend keys share runs, so hardware keys stay here.
+\-\-auth says how the store fetches from the remote. Default: your mode from mend keys mode. mend\-key signs with your Mend key on the server (see mend keys). bridge relays this machine's ssh\-agent while a mend command runs here, so hardware keys stay on your desk. ambient uses the server's own credentials.
 .SH OPTIONS
 .TP
 .B \-\-name <name>
 the project's name in Mend. Default: the repository's
 .TP
 .B \-\-auth <mode>
-ambient, mend\-key, or bridge. Default: ambient
+mend\-key, bridge, or ambient. Default: mend keys mode
 .SH EXAMPLES
 .PP
 .B mend adopt

package/man/mend-attach.1

@@ -1,4 +1,4 @@
-.TH MEND-ATTACH 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-ATTACH 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-attach \- reattach this terminal to a running session
 .SH SYNOPSIS

package/man/mend-codex.1

@@ -1,4 +1,4 @@
-.TH MEND-CODEX 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-CODEX 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-codex \- launch codex, claude, or opencode in a recorded worktree
 .SH SYNOPSIS

package/man/mend-completions.1

@@ -1,4 +1,4 @@
-.TH MEND-COMPLETIONS 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-COMPLETIONS 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-completions \- print the TAB\-completion hook
 .SH SYNOPSIS

package/man/mend-connect.1

@@ -1,4 +1,4 @@
-.TH MEND-CONNECT 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-CONNECT 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-connect \- send this machine's provider credential to the platform
 .SH SYNOPSIS

package/man/mend-continue.1

@@ -1,4 +1,4 @@
-.TH MEND-CONTINUE 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-CONTINUE 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-continue \- resume a session with its pending review follow\-up
 .SH SYNOPSIS

package/man/mend-doctor.1

@@ -1,4 +1,4 @@
-.TH MEND-DOCTOR 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-DOCTOR 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-doctor \- check this machine's setup
 .SH SYNOPSIS

package/man/mend-dotfiles-sync.1

@@ -1,4 +1,4 @@
-.TH MEND-DOTFILES-SYNC 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-DOTFILES-SYNC 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-dotfiles\-sync \- capture config files from this machine into your store
 .SH SYNOPSIS

package/man/mend-dotfiles.1

@@ -1,4 +1,4 @@
-.TH MEND-DOTFILES 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-DOTFILES 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-dotfiles \- your dotfiles on the server: repo and synced files
 .SH SYNOPSIS

package/man/mend-env-cluster.1

@@ -1,4 +1,4 @@
-.TH MEND-ENV-CLUSTER 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-ENV-CLUSTER 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-env\-cluster \- bind Kubernetes secrets and configmaps to the workspaces
 .SH SYNOPSIS

package/man/mend-env-load.1

@@ -1,4 +1,4 @@
-.TH MEND-ENV-LOAD 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-ENV-LOAD 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-env\-load \- load a .env into the project
 .SH SYNOPSIS

package/man/mend-env-show.1

@@ -1,4 +1,4 @@
-.TH MEND-ENV-SHOW 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-ENV-SHOW 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-env\-show \- what the project store holds: names only, never values
 .SH SYNOPSIS

package/man/mend-help.1

@@ -1,4 +1,4 @@
-.TH MEND-HELP 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-HELP 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-help \- this index, or one command's page
 .SH SYNOPSIS

package/man/mend-keys-init.1

@@ -1,11 +1,11 @@
-.TH MEND-KEYS-INIT 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-KEYS-INIT 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
-mend\-keys\-init \- generate this machine's Mend deploy key (ed25519)
+mend\-keys\-init \- create your Mend key (ed25519) on the server
 .SH SYNOPSIS
 .B mend keys init
 .br
 .SH DESCRIPTION
 .PP
-Creates a key under ~/.config/mend/keys for projects adopted with \-\-auth mend\-key. Add the public key on your git host as a deploy key.
+One key per user, held on the server, never copied anywhere. Add the public key to your git account's SSH keys and every repository you can reach works, from detached sessions and the phone too. For one repository only, add it as that repository's deploy key instead.
 .SH SEE ALSO
-mend(1), mend\-keys\-show(1), mend\-adopt(1)
+mend(1), mend\-keys\-show(1), mend\-keys\-mode(1), mend\-adopt(1)

package/man/mend-keys-mode.1

@@ -0,0 +1,11 @@
+.TH MEND-KEYS-MODE 1 "" "mend 0.21.0" "mend manual"
+.SH NAME
+mend\-keys\-mode \- how your remotes are reached: mend\-key or bridge
+.SH SYNOPSIS
+.B mend keys mode [mend\-key|bridge]
+.br
+.SH DESCRIPTION
+.PP
+mend\-key (the default) signs with your Mend key on the server and works whenever the server is up. bridge signs with this machine's ssh\-agent, so a hardware key never leaves your desk, but only while a mend command is running here. New projects adopt with this mode; a project's setup page can override it. Without a value, prints the current mode.
+.SH SEE ALSO
+mend(1), mend\-keys\-init(1), mend\-keys\-share(1)

package/man/mend-keys-share.1

@@ -1,4 +1,4 @@
-.TH MEND-KEYS-SHARE 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-KEYS-SHARE 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-keys\-share \- relay this machine's ssh\-agent to the server
 .SH SYNOPSIS
@@ -7,5 +7,7 @@ mend\-keys\-share \- relay this machine's ssh\-agent to the server
 .SH DESCRIPTION
 .PP
 Bridge mode for projects adopted with \-\-auth bridge: the server's git operations sign with the keys in this machine's ssh\-agent, so hardware keys never leave here. Runs until Ctrl\-C.
+.PP
+When your mode is bridge (mend keys mode), every attaching mend command and the dashboard do this on their own for as long as they run, so this command is for a machine that is not running one. The server takes one signer at a time; a newer share replaces the older one.
 .SH SEE ALSO
-mend(1), mend\-adopt(1)
+mend(1), mend\-keys\-mode(1), mend\-adopt(1)

package/man/mend-keys-show.1

@@ -1,11 +1,11 @@
-.TH MEND-KEYS-SHOW 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-KEYS-SHOW 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
-mend\-keys\-show \- print the public key
+mend\-keys\-show \- print your Mend public key
 .SH SYNOPSIS
 .B mend keys show
 .br
 .SH DESCRIPTION
 .PP
-The key to add as a deploy key on your git host.
+The key to add to your git account's SSH keys, or as a deploy key on one repository.
 .SH SEE ALSO
 mend(1), mend\-keys\-init(1)

package/man/mend-login.1

@@ -1,4 +1,4 @@
-.TH MEND-LOGIN 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-LOGIN 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-login \- sign this terminal in through the browser
 .SH SYNOPSIS

package/man/mend-logout.1

@@ -1,4 +1,4 @@
-.TH MEND-LOGOUT 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-LOGOUT 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-logout \- revoke this terminal's device token and forget it
 .SH SYNOPSIS

package/man/mend-man.1

@@ -1,4 +1,4 @@
-.TH MEND-MAN 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-MAN 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-man \- one command's page, or the whole manual, in man
 .SH SYNOPSIS

package/man/mend-pair.1

@@ -1,4 +1,4 @@
-.TH MEND-PAIR 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-PAIR 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-pair \- pair a phone or a second machine
 .SH SYNOPSIS

package/man/mend-projects.1

@@ -1,4 +1,4 @@
-.TH MEND-PROJECTS 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-PROJECTS 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-projects \- adopted projects and their live sessions
 .SH SYNOPSIS

package/man/mend-refresh.1

@@ -1,4 +1,4 @@
-.TH MEND-REFRESH 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-REFRESH 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-refresh \- fetch origin's branches into the store
 .SH SYNOPSIS

package/man/mend-rejoin.1

@@ -1,4 +1,4 @@
-.TH MEND-REJOIN 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-REJOIN 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-rejoin \- attach if live, otherwise resume
 .SH SYNOPSIS

package/man/mend-resume.1

@@ -1,4 +1,4 @@
-.TH MEND-RESUME 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-RESUME 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-resume \- rejoin a settled session with its state restored
 .SH SYNOPSIS

package/man/mend-run.1

@@ -1,4 +1,4 @@
-.TH MEND-RUN 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-RUN 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-run \- run any command as a session
 .SH SYNOPSIS

package/man/mend-service-add.1

@@ -1,4 +1,4 @@
-.TH MEND-SERVICE-ADD 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SERVICE-ADD 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-service\-add \- adopt a port something in the workspace already listens on
 .SH SYNOPSIS

package/man/mend-service-connect.1

@@ -1,4 +1,4 @@
-.TH MEND-SERVICE-CONNECT 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SERVICE-CONNECT 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-service\-connect \- bring live Services to this machine's loopback
 .SH SYNOPSIS

package/man/mend-service-init.1

@@ -1,4 +1,4 @@
-.TH MEND-SERVICE-INIT 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SERVICE-INIT 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-service\-init \- scaffold mend.toml from package.json and compose ports
 .SH SYNOPSIS

package/man/mend-service-list.1

@@ -1,4 +1,4 @@
-.TH MEND-SERVICE-LIST 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SERVICE-LIST 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-service\-list \- every live service and its observed state
 .SH SYNOPSIS

package/man/mend-service-logs.1

@@ -1,4 +1,4 @@
-.TH MEND-SERVICE-LOGS 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SERVICE-LOGS 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-service\-logs \- follow a supervised service's output
 .SH SYNOPSIS

package/man/mend-service-restart.1

@@ -1,4 +1,4 @@
-.TH MEND-SERVICE-RESTART 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SERVICE-RESTART 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-service\-restart \- re\-run a service's recorded command, same URL
 .SH SYNOPSIS

package/man/mend-service-run.1

@@ -1,4 +1,4 @@
-.TH MEND-SERVICE-RUN 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SERVICE-RUN 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-service\-run \- start and supervise a server in the session's workspace
 .SH SYNOPSIS

package/man/mend-service-stop.1

@@ -1,4 +1,4 @@
-.TH MEND-SERVICE-STOP 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SERVICE-STOP 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-service\-stop \- stop a service and close its host port
 .SH SYNOPSIS

package/man/mend-sessions.1

@@ -1,4 +1,4 @@
-.TH MEND-SESSIONS 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SESSIONS 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-sessions \- sessions with their review facts
 .SH SYNOPSIS

package/man/mend-shell.1

@@ -1,4 +1,4 @@
-.TH MEND-SHELL 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SHELL 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-shell \- open a shell in a live session's workspace
 .SH SYNOPSIS

package/man/mend-skills-push.1

@@ -1,4 +1,4 @@
-.TH MEND-SKILLS-PUSH 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SKILLS-PUSH 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-skills\-push \- upload ~/.agents/skills into the library
 .SH SYNOPSIS

package/man/mend-skills.1

@@ -1,4 +1,4 @@
-.TH MEND-SKILLS 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SKILLS 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-skills \- your skill library on the server, or a project's
 .SH SYNOPSIS

package/man/mend-ssh-setup.1

@@ -1,4 +1,4 @@
-.TH MEND-SSH-SETUP 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SSH-SETUP 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-ssh\-setup \- make this machine ready to ssh into workspaces, once
 .SH SYNOPSIS

package/man/mend-ssh.1

@@ -1,4 +1,4 @@
-.TH MEND-SSH 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-SSH 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-ssh \- workspace SSH status: gateway, registered keys, ssh config
 .SH SYNOPSIS

package/man/mend-stop.1

@@ -1,4 +1,4 @@
-.TH MEND-STOP 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-STOP 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-stop \- stop the agent; the record and the review remain
 .SH SYNOPSIS

package/man/mend-ui.1

@@ -1,4 +1,4 @@
-.TH MEND-UI 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-UI 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-ui \- the dashboard: every project and session, live
 .SH SYNOPSIS

package/man/mend-version.1

@@ -1,4 +1,4 @@
-.TH MEND-VERSION 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-VERSION 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-version \- this CLI's version, and the server's when it answers
 .SH SYNOPSIS

package/man/mend-worktrees.1

@@ -1,4 +1,4 @@
-.TH MEND-WORKTREES 1 "" "mend 0.20.0" "mend manual"
+.TH MEND-WORKTREES 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-worktrees \- every worktree and the sessions inside it
 .SH SYNOPSIS

package/man/mend.1

@@ -1,4 +1,4 @@
-.TH MEND 1 "" "mend 0.20.0" "mend manual"
+.TH MEND 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend \- the agent workbench
 .SH SYNOPSIS
@@ -112,10 +112,13 @@ your dotfiles on the server: repo and synced files
 capture config files from this machine into your store
 .TP
 .B mend keys init
-generate this machine's Mend deploy key (ed25519)
+create your Mend key (ed25519) on the server
 .TP
 .B mend keys show
-print the public key
+print your Mend public key
+.TP
+.B mend keys mode
+how your remotes are reached: mend\-key or bridge
 .TP
 .B mend keys share
 relay this machine's ssh\-agent to the server
@@ -162,4 +165,4 @@ url, token, and device id from mend login
 .B ~/.config/mend/keys/
 the deploy key from mend keys init
 .SH SEE ALSO
-mend\-login(1), mend\-connect(1), mend\-adopt(1), mend\-codex(1), mend\-pair(1), mend\-doctor(1), mend\-ui(1), mend\-attach(1), mend\-stop(1), mend\-shell(1), mend\-run(1), mend\-continue(1), mend\-resume(1), mend\-rejoin(1), mend\-sessions(1), mend\-worktrees(1), mend\-projects(1), mend\-refresh(1), mend\-service\-run(1), mend\-service\-add(1), mend\-service\-connect(1), mend\-service\-list(1), mend\-service\-logs(1), mend\-service\-restart(1), mend\-service\-stop(1), mend\-service\-init(1), mend\-env\-show(1), mend\-env\-load(1), mend\-env\-cluster(1), mend\-skills(1), mend\-skills\-push(1), mend\-dotfiles(1), mend\-dotfiles\-sync(1), mend\-keys\-init(1), mend\-keys\-show(1), mend\-keys\-share(1), mend\-ssh(1), mend\-ssh\-setup(1), mend\-accounts(1), mend\-logout(1), mend\-completions(1), mend\-version(1), mend\-help(1), mend\-man(1)
+mend\-login(1), mend\-connect(1), mend\-adopt(1), mend\-codex(1), mend\-pair(1), mend\-doctor(1), mend\-ui(1), mend\-attach(1), mend\-stop(1), mend\-shell(1), mend\-run(1), mend\-continue(1), mend\-resume(1), mend\-rejoin(1), mend\-sessions(1), mend\-worktrees(1), mend\-projects(1), mend\-refresh(1), mend\-service\-run(1), mend\-service\-add(1), mend\-service\-connect(1), mend\-service\-list(1), mend\-service\-logs(1), mend\-service\-restart(1), mend\-service\-stop(1), mend\-service\-init(1), mend\-env\-show(1), mend\-env\-load(1), mend\-env\-cluster(1), mend\-skills(1), mend\-skills\-push(1), mend\-dotfiles(1), mend\-dotfiles\-sync(1), mend\-keys\-init(1), mend\-keys\-show(1), mend\-keys\-mode(1), mend\-keys\-share(1), mend\-ssh(1), mend\-ssh\-setup(1), mend\-accounts(1), mend\-logout(1), mend\-completions(1), mend\-version(1), mend\-help(1), mend\-man(1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/mend",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "The mend CLI: adopt a repository into Mend's store, launch your coding agent in a recorded session worktree, detach and reattach from any terminal",
   "keywords": [
     "claude-code",