@sealant/mend 0.19.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/clipboard.js

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+const IMAGE_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
+/** The first image type this reader accepts from a clipboard's offered list. */
+export const pickImageType = (offered) => {
+    const types = offered.split(/\s+/).map((type) => type.trim().toLowerCase());
+    for (const type of IMAGE_TYPES)
+        if (types.includes(type))
+            return type;
+    return null;
+};
+/**
+ * AppleScript's `«data PNGf…»` literal: the PNG bytes as hex, from
+ * `the clipboard as «class PNGf»`. Null when the clipboard held no image.
+ */
+export const parsePngfHex = (output) => {
+    const match = /«data PNGf([0-9A-Fa-f]+)»/.exec(output.trim());
+    if (match?.[1] === undefined || match[1].length === 0)
+        return null;
+    return Buffer.from(match[1], "hex");
+};
+const MAX_BYTES = 32 * 1024 * 1024;
+/** One clipboard tool call; null when the tool is missing, fails, or times out. */
+const run = (command, args) => new Promise((resolve) => {
+    execFile(command, [...args], { encoding: "buffer", maxBuffer: MAX_BYTES, timeout: 3000 }, (error, stdout) => {
+        resolve(error === null ? stdout : null);
+    });
+});
+const fromWayland = async () => {
+    const offered = await run("wl-paste", ["--list-types"]);
+    if (offered === null)
+        return null;
+    const mediaType = pickImageType(offered.toString("utf8"));
+    if (mediaType === null)
+        return null;
+    const bytes = await run("wl-paste", ["--no-newline", "--type", mediaType]);
+    return bytes === null || bytes.length === 0 ? null : { bytes, mediaType };
+};
+const fromX11 = async () => {
+    const offered = await run("xclip", ["-selection", "clipboard", "-t", "TARGETS", "-o"]);
+    if (offered === null)
+        return null;
+    const mediaType = pickImageType(offered.toString("utf8"));
+    if (mediaType === null)
+        return null;
+    const bytes = await run("xclip", ["-selection", "clipboard", "-t", mediaType, "-o"]);
+    return bytes === null || bytes.length === 0 ? null : { bytes, mediaType };
+};
+const fromMac = async () => {
+    const output = await run("osascript", ["-e", "the clipboard as «class PNGf»"]);
+    if (output === null)
+        return null;
+    const bytes = parsePngfHex(output.toString("utf8"));
+    return bytes === null ? null : { bytes, mediaType: "image/png" };
+};
+/**
+ * Read an image off the clipboard: wl-paste on Wayland, xclip on X11,
+ * osascript on macOS. Null when there is no image or no way to ask — the
+ * caller then forwards the keystroke as it was.
+ */
+export const readClipboardImage = async (platform = process.platform, env = process.env) => {
+    if (platform === "darwin")
+        return fromMac();
+    if (platform !== "linux" && platform !== "freebsd" && platform !== "openbsd")
+        return null;
+    if (env["WAYLAND_DISPLAY"] !== undefined && env["WAYLAND_DISPLAY"] !== "") {
+        const image = await fromWayland();
+        if (image !== null)
+            return image;
+    }
+    if (env["DISPLAY"] !== undefined && env["DISPLAY"] !== "")
+        return fromX11();
+    return null;
+};

package/dist/dashboard-model.js

@@ -160,15 +160,10 @@ export const pseudoGroup = (session, item) => ({
     live: LIVE_STATUSES.has(session.status) ? 1 : 0,
     annotation: item(session).annotation,
 });
-export const deriveRows = (groups) => groups.flatMap((group) => {
-    const only = group.sessions.length === 1 ? group.sessions[0] : undefined;
-    if (only !== undefined)
-        return [{ kind: "session", group, item: only }];
-    return [
-        { kind: "worktree", group },
-        ...group.sessions.map((item) => ({ kind: "session", group, item })),
-    ];
-});
+export const deriveRows = (groups) => groups.flatMap((group) => [
+    { kind: "worktree", group },
+    ...group.sessions.map((item) => ({ kind: "session", group, item })),
+]);
 export const rowKeyOf = (row) => row.kind === "worktree" ? `wt:${row.group.key}` : `s:${row.item.session.id}`;
 /** The picker's rows: resume offers the same harness first, then the crossings. */
 export const deriveHarnesses = (resuming) => {

package/dist/dashboard.js

@@ -2,8 +2,8 @@ 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 { deriveHarnesses, deriveProjects, advanceFromBase, deriveRows, deriveWorktrees, filterBranches, foldGroupStatus, labelIsIdentity, rowKeyOf, worktreeDisplayName, fetchWorkbench, liveProtocolOf, liveShellOf, mapWorkbenchSessions, markSessionStopped, removeWorktreeGroup, prependSession, removeSession, replaceSession, WORKBENCH_KEY, } from "./dashboard-model.js";
+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";
 import { cwdFacts, HARNESS_COMMANDS, isPendingId, LIVE_STATUSES, matchProjectByCwd, normalizeProjectName, pendingId, } from "./shared.js";
@@ -58,26 +58,15 @@ const ProcessLines = ({ processes, services, indent, }) => (_jsxs(_Fragment, { c
                                 : process.kind === "agent-external"
                                     ? " · external"
                                     : "", ` ${process.status}`] })] }) }, process.id))), services.map((service) => (_jsx("box", { height: 1, flexShrink: 0, backgroundColor: "transparent", children: _jsxs("text", { height: 1, bg: "transparent", children: [_jsx("span", { fg: FAINT, children: indent }), _jsx("span", { fg: service.status === "reachable" ? INK_2 : MUTED, children: `${service.label ?? service.id.slice(0, 6)} :${service.workspacePort ?? "?"}${service.protocol === "udp" ? "u" : ""}→${service.hostPort ?? "?"}` }), _jsx("span", { fg: FAINT, children: ` ${service.status}` })] }) }, service.id)))] }));
-/**
- * A lone-session worktree, combined into one row (today's density): the
- * worktree name leads, everything live inside hangs underneath as facts.
- */
-const CombinedRow = ({ group, item, selected, }) => {
-    const { session, annotation, services, processes } = item;
-    const color = STATUS_COLOR[session.status] ?? MUTED;
-    const age = timeAgo(session.createdAt).replace(" ago", "");
-    const trailingLabel = labelIsIdentity(session) ? "" : (session.label ?? "");
-    return (_jsxs("box", { flexShrink: 0, flexDirection: "column", backgroundColor: "transparent", children: [_jsx("box", { height: 1, flexShrink: 0, backgroundColor: selected ? WASH : "transparent", children: _jsxs("text", { height: 1, bg: "transparent", children: [_jsx(Gutter, { selected: selected }), _jsx("span", { fg: INK, children: group.name.slice(0, 30).padEnd(31) }), _jsx("span", { fg: color, children: session.status.padEnd(10) }), _jsx("span", { fg: FAINT, children: age.padEnd(9) }), _jsx("span", { fg: MUTED, children: session.harness.padEnd(10) }), annotation !== undefined && annotation.openComments > 0 ? (_jsx("span", { fg: MUTED, children: `${annotation.openComments} open  ` })) : null, _jsx("span", { fg: FAINT, children: trailingLabel.slice(0, 40) })] }) }), _jsx(ProcessLines, { processes: processes, services: services, indent: "     └ " })] }));
-};
-/** A shared worktree's header: the place, its folded status, its member facts. */
+/** A worktree's header: the place, its folded status, its member facts. */
 const WorktreeHeaderRow = ({ group, selected, }) => {
     const folded = foldGroupStatus(group);
     const color = group.live > 0 ? (STATUS_COLOR[folded] ?? MUTED) : FAINT;
     const age = timeAgo(group.sessions.at(-1)?.session.createdAt ?? group.createdAt).replace(" ago", "");
     const open = group.annotation?.openComments ?? 0;
-    return (_jsx("box", { height: 1, flexShrink: 0, backgroundColor: selected ? WASH : "transparent", children: _jsxs("text", { height: 1, bg: "transparent", children: [_jsx(Gutter, { selected: selected }), _jsx("span", { fg: INK, children: group.name.slice(0, 30).padEnd(31) }), _jsx("span", { fg: color, children: (group.live > 0 ? folded : "settled").padEnd(10) }), _jsx("span", { fg: FAINT, children: age.padEnd(9) }), _jsx("span", { fg: MUTED, children: `${group.sessions.length} sessions` }), open > 0 ? _jsx("span", { fg: MUTED, children: ` · ${open} open` }) : null] }) }));
+    return (_jsx("box", { height: 1, flexShrink: 0, backgroundColor: selected ? WASH : "transparent", children: _jsxs("text", { height: 1, bg: "transparent", children: [_jsx(Gutter, { selected: selected }), _jsx("span", { fg: INK, children: group.name.slice(0, 30).padEnd(31) }), _jsx("span", { fg: color, children: (group.live > 0 ? folded : "settled").padEnd(10) }), _jsx("span", { fg: FAINT, children: age.padEnd(9) }), _jsx("span", { fg: MUTED, children: `${group.sessions.length} session${group.sessions.length === 1 ? "" : "s"}` }), open > 0 ? _jsx("span", { fg: MUTED, children: ` · ${open} open` }) : null] }) }));
 };
-/** One conversation inside a shared worktree — the label is its identity. */
+/** One conversation inside a worktree — the label is its identity. */
 const SessionChildRow = ({ item, selected, }) => {
     const { session, services, processes } = item;
     const color = STATUS_COLOR[session.status] ?? MUTED;
@@ -135,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();
@@ -154,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);
@@ -208,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(() => {
@@ -1062,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))) : row.group.sessions.length === 1 ? (_jsx(CombinedRow, { group: row.group, item: row.item, 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" },
@@ -87,6 +87,7 @@ export const COMMANDS = [
             "mend codex, mend claude, and mend opencode are the same command with a different harness. The session runs in a workspace on the platform, in its own git worktree, and everything it does is recorded. This terminal attaches to it.",
             "The worktree's name is asked first. --name skips the ask; an existing name joins that worktree as a new session. --worktree joins only and fails if the name is unknown. A quoted prompt becomes the first message.",
             "Detach with Ctrl+] and the session keeps running. Reattach from any terminal with mend attach, or from the phone.",
+            "Ctrl+V with an image on this machine's clipboard sends the image to the session and pastes its path; codex and claude read it. Needs wl-paste on Wayland, xclip on X11, nothing extra on macOS.",
         ],
         options: [
             { flag: "--name <worktree>", text: "name the worktree; an existing name joins it" },
@@ -156,6 +157,7 @@ export const COMMANDS = [
         description: [
             sessionArg,
             "A session that was picked up on the phone is taken back into this terminal: the phone's agent ends and the same conversation continues here.",
+            "Ctrl+V with an image on this machine's clipboard sends the image to the session and pastes its path; codex and claude read it. Needs wl-paste on Wayland, xclip on X11, nothing extra on macOS.",
         ],
         see: ["stop", "rejoin", "shell"],
     },
@@ -469,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",
@@ -491,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 ───────────────────────────────────────────────────────
     {