@sealant/mend 0.14.0 → 0.15.0

package/dist/dashboard-model.js

@@ -0,0 +1,202 @@
+import { HARNESS_COMMANDS, LIVE_STATUSES } from "./shared.js";
+/**
+ * The worktree IS the session's identity (one worktree per session): its
+ * branch, with the noisy default prefix receded. What you are working on
+ * leads every row; the harness is a fact about it, not its name.
+ */
+export const worktreeName = (branch) => branch.startsWith("mend/") ? branch.slice("mend/".length) : branch;
+/**
+ * What to call an UNNAMED worktree: its branch is `mend/session/<uuid>` —
+ * noise nobody recognizes — so the auto-name label stands in, and before one
+ * lands, the short session id. A named worktree is always its own name.
+ */
+export const worktreeDisplayName = (session) => {
+    const name = worktreeName(session.branch);
+    if (!name.startsWith("session/"))
+        return name;
+    return session.label ?? `session ${session.id.slice(0, 8)}`;
+};
+/** True when the label already IS the row's identity — don't repeat it. */
+export const labelIsIdentity = (session) => worktreeName(session.branch).startsWith("session/") && session.label !== null;
+export const WORKBENCH_KEY = ["workbench"];
+export const fetchWorkbench = async (ctx) => {
+    const projects = await ctx.api("GET", "/projects");
+    const [fetched, services] = await Promise.all([
+        Promise.all(projects.map((project) => ctx.api("GET", `/projects/${project.id}`))),
+        ctx.api("GET", "/services"),
+    ]);
+    const servicesBySession = new Map();
+    for (const service of services) {
+        const bucket = servicesBySession.get(service.sessionId) ?? [];
+        bucket.push(service);
+        servicesBySession.set(service.sessionId, bucket);
+    }
+    // What lives in each LIVE worktree: the agent and shells come from the
+    // session detail (settled sessions have nothing live — no fetch for them).
+    const liveSessions = fetched.flatMap((detail) => detail.sessions.filter((session) => LIVE_STATUSES.has(session.status)));
+    const detailed = await Promise.all(liveSessions.map(async (session) => {
+        try {
+            return await ctx.api("GET", `/sessions/${session.id}`);
+        }
+        catch {
+            return null;
+        }
+    }));
+    const processesBySession = new Map();
+    for (const detail of detailed) {
+        if (detail === null)
+            continue;
+        processesBySession.set(detail.session.id, detail.processes.filter((process) => process.exitedAt === null && process.kind !== "service"));
+    }
+    return {
+        projects,
+        details: new Map(fetched.map((detail) => [detail.project.id, detail])),
+        servicesBySession,
+        processesBySession,
+    };
+};
+// ─── optimistic cache surgery: pure Workbench → Workbench ───────────────────
+/** Apply `f` to every session row in every project detail. */
+export const mapWorkbenchSessions = (data, f) => ({
+    ...data,
+    details: new Map([...data.details].map(([id, detail]) => [id, { ...detail, sessions: detail.sessions.map(f) }])),
+});
+export const mapProjectSessions = (data, projectId, f) => {
+    const detail = data.details.get(projectId);
+    if (detail === undefined)
+        return data;
+    const details = new Map(data.details);
+    details.set(projectId, { ...detail, sessions: f(detail.sessions) });
+    return { ...data, details };
+};
+export const prependSession = (data, projectId, session) => mapProjectSessions(data, projectId, (sessions) => [session, ...sessions]);
+export const replaceSession = (data, projectId, oldId, session) => mapProjectSessions(data, projectId, (sessions) => sessions.map((candidate) => (candidate.id === oldId ? session : candidate)));
+export const removeSession = (data, projectId, sessionId) => mapProjectSessions(data, projectId, (sessions) => sessions.filter((candidate) => candidate.id !== sessionId));
+export const deriveProjects = (data) => (data?.projects ?? []).map((project) => {
+    const detail = data?.details.get(project.id);
+    const sessions = detail?.sessions ?? [];
+    const live = sessions.filter((s) => LIVE_STATUSES.has(s.status)).length;
+    const open = (detail?.annotations ?? []).reduce((sum, a) => sum + a.openComments, 0);
+    return { project, total: sessions.length, live, open };
+});
+export const bySessionRecency = (a, b) => {
+    const aLive = LIVE_STATUSES.has(a.status) ? 1 : 0;
+    const bLive = LIVE_STATUSES.has(b.status) ? 1 : 0;
+    if (aLive !== bLive)
+        return bLive - aLive;
+    return b.createdAt.localeCompare(a.createdAt);
+};
+export const toSessionItem = (data, detail) => (session) => ({
+    session,
+    annotation: detail.annotations.find((a) => a.sessionId === session.id),
+    services: data.servicesBySession.get(session.id) ?? [],
+    processes: data.processesBySession.get(session.id) ?? [],
+});
+export const deriveWorktrees = (data, projectId) => {
+    if (data === undefined || projectId === null)
+        return [];
+    const detail = data.details.get(projectId);
+    if (detail === undefined)
+        return [];
+    const item = toSessionItem(data, detail);
+    const sorted = detail.sessions.toSorted(bySessionRecency);
+    const groups = [];
+    if (detail.worktrees !== undefined) {
+        const claimed = new Set();
+        for (const worktree of detail.worktrees) {
+            const members = sorted.filter((session) => session.worktreeId === worktree.id);
+            for (const member of members)
+                claimed.add(member.id);
+            groups.push({
+                key: worktree.id,
+                id: worktree.id,
+                name: worktree.name.startsWith("wt-")
+                    ? (members.find((m) => m.label !== null)?.label ??
+                        (members[0] === undefined ? worktree.name : `session ${members[0].id.slice(0, 8)}`))
+                    : worktree.name,
+                branch: worktree.branch,
+                baseRef: worktree.baseRef,
+                createdAt: worktree.createdAt,
+                sessions: members.map(item),
+                live: members.filter((session) => LIVE_STATUSES.has(session.status)).length,
+                annotation: detail.annotations.find((a) => members.some((m) => m.id === a.sessionId)),
+            });
+        }
+        // Optimistic pending rows have no worktree yet — each is its own group.
+        for (const session of sorted) {
+            if (claimed.has(session.id))
+                continue;
+            groups.push(pseudoGroup(session, item));
+        }
+    }
+    else {
+        for (const session of sorted)
+            groups.push(pseudoGroup(session, item));
+    }
+    return groups.toSorted((a, b) => {
+        if (a.live > 0 !== b.live > 0)
+            return a.live > 0 ? -1 : 1;
+        const aNewest = a.sessions[0]?.session.createdAt ?? a.createdAt;
+        const bNewest = b.sessions[0]?.session.createdAt ?? b.createdAt;
+        return bNewest.localeCompare(aNewest);
+    });
+};
+export const pseudoGroup = (session, item) => ({
+    key: session.id,
+    id: null,
+    name: worktreeDisplayName(session),
+    branch: session.branch,
+    baseRef: session.baseRef,
+    createdAt: session.createdAt,
+    sessions: [item(session)],
+    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 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) => {
+    if (resuming !== null) {
+        const others = Object.keys(HARNESS_COMMANDS).filter((h) => h !== resuming.harness);
+        return [
+            {
+                harness: null,
+                label: resuming.harness,
+                hint: "same harness — native resume, conversation intact",
+            },
+            ...others.map((harness) => ({
+                harness,
+                label: harness,
+                hint: harness === "shell"
+                    ? "a bash in the worktree — resume either agent from inside"
+                    : "the conversation crosses as a distilled prompt",
+            })),
+        ];
+    }
+    return Object.keys(HARNESS_COMMANDS).map((harness) => ({
+        harness,
+        label: harness,
+        hint: harness === "shell"
+            ? "a plain bash session — new worktree, recorded"
+            : `mend ${harness} — new worktree, recorded session`,
+    }));
+};
+/** The worktree's folded status word: waiting wins, then running, then idle. */
+export const foldGroupStatus = (group) => {
+    const statuses = group.sessions.map((item) => item.session.status);
+    if (statuses.includes("waiting"))
+        return "waiting";
+    if (statuses.includes("running") || statuses.includes("starting"))
+        return "running";
+    if (statuses.includes("idle"))
+        return "idle";
+    return statuses[0] ?? "idle";
+};

package/dist/dashboard.js

@@ -3,12 +3,12 @@ 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, deriveRows, deriveWorktrees, foldGroupStatus, labelIsIdentity, rowKeyOf, worktreeDisplayName, fetchWorkbench, mapWorkbenchSessions, 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";
 import { openUrl } from "./terminal.js";
 import { COBALT, FAINT, INK, INK_2, MUTED, RED, RULE, WASH } from "./tui-theme.js";
-import { createSseParser, eventFamilies } from "./workbench-events.js";
 // Near-mono on purpose: a status is a word, and only an observed failure
 // earns color. Live states read at full ink; settled ones recede.
 const STATUS_COLOR = {
@@ -34,96 +34,7 @@ const timeAgo = (iso) => {
         return `${hours}h ago`;
     return `${Math.floor(hours / 24)}d ago`;
 };
-const WORKBENCH_KEY = ["workbench"];
-const fetchWorkbench = async (ctx) => {
-    const projects = await ctx.api("GET", "/projects");
-    const [fetched, services] = await Promise.all([
-        Promise.all(projects.map((project) => ctx.api("GET", `/projects/${project.id}`))),
-        ctx.api("GET", "/services"),
-    ]);
-    const servicesBySession = new Map();
-    for (const service of services) {
-        const bucket = servicesBySession.get(service.sessionId) ?? [];
-        bucket.push(service);
-        servicesBySession.set(service.sessionId, bucket);
-    }
-    return {
-        projects,
-        details: new Map(fetched.map((detail) => [detail.project.id, detail])),
-        servicesBySession,
-    };
-};
-// ─── optimistic cache surgery: pure Workbench → Workbench ───────────────────
-/** Apply `f` to every session row in every project detail. */
-const mapWorkbenchSessions = (data, f) => ({
-    ...data,
-    details: new Map([...data.details].map(([id, detail]) => [id, { ...detail, sessions: detail.sessions.map(f) }])),
-});
-const mapProjectSessions = (data, projectId, f) => {
-    const detail = data.details.get(projectId);
-    if (detail === undefined)
-        return data;
-    const details = new Map(data.details);
-    details.set(projectId, { ...detail, sessions: f(detail.sessions) });
-    return { ...data, details };
-};
-const prependSession = (data, projectId, session) => mapProjectSessions(data, projectId, (sessions) => [session, ...sessions]);
-const replaceSession = (data, projectId, oldId, session) => mapProjectSessions(data, projectId, (sessions) => sessions.map((candidate) => (candidate.id === oldId ? session : candidate)));
-const removeSession = (data, projectId, sessionId) => mapProjectSessions(data, projectId, (sessions) => sessions.filter((candidate) => candidate.id !== sessionId));
-const deriveProjects = (data) => (data?.projects ?? []).map((project) => {
-    const detail = data?.details.get(project.id);
-    const sessions = detail?.sessions ?? [];
-    const live = sessions.filter((s) => LIVE_STATUSES.has(s.status)).length;
-    const open = (detail?.annotations ?? []).reduce((sum, a) => sum + a.openComments, 0);
-    return { project, total: sessions.length, live, open };
-});
-const deriveSessions = (data, projectId) => {
-    if (data === undefined || projectId === null)
-        return [];
-    const detail = data.details.get(projectId);
-    if (detail === undefined)
-        return [];
-    return detail.sessions
-        .toSorted((a, b) => {
-        const aLive = LIVE_STATUSES.has(a.status) ? 1 : 0;
-        const bLive = LIVE_STATUSES.has(b.status) ? 1 : 0;
-        if (aLive !== bLive)
-            return bLive - aLive;
-        return b.createdAt.localeCompare(a.createdAt);
-    })
-        .map((session) => ({
-        session,
-        annotation: detail.annotations.find((a) => a.sessionId === session.id),
-        services: data.servicesBySession.get(session.id) ?? [],
-    }));
-};
-/** The picker's rows: resume offers the same harness first, then the crossings. */
-const deriveHarnesses = (resuming) => {
-    if (resuming !== null) {
-        const others = Object.keys(HARNESS_COMMANDS).filter((h) => h !== resuming.harness);
-        return [
-            {
-                harness: null,
-                label: resuming.harness,
-                hint: "same harness — native resume, conversation intact",
-            },
-            ...others.map((harness) => ({
-                harness,
-                label: harness,
-                hint: harness === "shell"
-                    ? "a bash in the worktree — resume either agent from inside"
-                    : "the conversation crosses as a distilled prompt",
-            })),
-        ];
-    }
-    return Object.keys(HARNESS_COMMANDS).map((harness) => ({
-        harness,
-        label: harness,
-        hint: harness === "shell"
-            ? "a plain bash session — new worktree, recorded"
-            : `mend ${harness} — new worktree, recorded session`,
-    }));
-};
+import { createSseParser, eventFamilies } from "./workbench-events.js";
 // ─── panes and rows ─────────────────────────────────────────────────────────
 const Gutter = ({ selected }) => (_jsx("span", { fg: selected ? COBALT : FAINT, children: selected ? "▌ " : "  " }));
 /**
@@ -138,23 +49,39 @@ const paneScrollStyle = {
     contentOptions: { backgroundColor: "transparent" },
 };
 const ProjectRow = ({ item, selected, nameWidth, }) => (_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: item.project.name.padEnd(nameWidth) }), _jsx("span", { fg: item.total === 0 ? FAINT : MUTED, children: `  ${item.total}` }), item.live > 0 ? _jsx("span", { fg: MUTED, children: ` · ${item.live} live` }) : null, item.open > 0 ? _jsx("span", { fg: MUTED, children: ` · ${item.open}` }) : null] }) }));
+const ProcessLines = ({ processes, services, indent, }) => (_jsxs(_Fragment, { children: [processes.map((process) => (_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: INK_2, children: process.kind === "shell"
+                            ? (process.label ?? "shell")
+                            : (process.harness ?? process.kind) }), _jsxs("span", { fg: FAINT, children: [process.kind === "agent-protocol"
+                                ? " · protocol"
+                                : 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)))] }));
 /**
- * The worktree IS the session's identity (one worktree per session): its
- * branch, with the noisy default prefix receded. What you are working on
- * leads every row; the harness is a fact about it, not its name.
- */
-const worktreeName = (branch) => branch.startsWith("mend/") ? branch.slice("mend/".length) : branch;
-/**
- * One worktree, grouped: the session line leads with the worktree name, and
- * everything live inside it — its Services — hangs underneath. The child
- * rows are facts, not targets: selection stays on the worktree line.
+ * A lone-session worktree, combined into one row (today's density): the
+ * worktree name leads, everything live inside hangs underneath as facts.
  */
-const SessionRow = ({ item, selected, }) => {
-    const { session, annotation, services } = item;
+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. */
+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] }) }));
+};
+/** One conversation inside a shared worktree — the label is its identity. */
+const SessionChildRow = ({ item, selected, }) => {
+    const { session, services, processes } = item;
     const color = STATUS_COLOR[session.status] ?? MUTED;
     const age = timeAgo(session.createdAt).replace(" ago", "");
-    const worktree = worktreeName(session.branch);
-    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: worktree.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: (session.label ?? "").slice(0, 40) })] }) }), services.map((service) => (_jsx("box", { height: 1, flexShrink: 0, backgroundColor: "transparent", children: _jsxs("text", { height: 1, bg: "transparent", children: [_jsx("span", { fg: FAINT, children: "     └ " }), _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)))] }));
+    const name = session.label ?? `session ${session.id.slice(0, 8)}`;
+    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: FAINT, children: "  └ " }), _jsx("span", { fg: INK, children: name.slice(0, 26).padEnd(27) }), _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) })] }) }), _jsx(ProcessLines, { processes: processes, services: services, indent: "       └ " })] }));
 };
 const HarnessRow = ({ item, selected, }) => (_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: item.label.padEnd(12) }), _jsx("span", { fg: FAINT, children: item.hint })] }) }));
 /**
@@ -218,6 +145,7 @@ const App = ({ ctx, onQuit }) => {
     });
     const [focusState, setFocus] = useState("sessions");
     const [projectKey, setProjectKey] = useState(null);
+    /** A row key (`wt:<id>` | `s:<id>`), so selection survives regrouping. */
     const [sessionKey, setSessionKey] = useState(null);
     const [picker, setPicker] = useState(null);
     const [pickerIndex, setPickerIndex] = useState(0);
@@ -250,11 +178,23 @@ const App = ({ ctx, onQuit }) => {
             ? 0
             : projectItems.findIndex((p) => p.project.id === homeProject.id));
     const selectedProject = projectItems[projectIndex] ?? null;
-    const sessionItems = deriveSessions(data, selectedProject?.project.id ?? null);
-    const sessionIndexRaw = sessionKey === null ? -1 : sessionItems.findIndex((s) => s.session.id === sessionKey);
-    const sessionIndex = sessionIndexRaw === -1 ? 0 : sessionIndexRaw;
-    const selectedSession = sessionItems[sessionIndex] ?? null;
+    const worktreeGroups = deriveWorktrees(data, selectedProject?.project.id ?? null);
+    const rows = deriveRows(worktreeGroups);
+    const rowIndexRaw = sessionKey === null ? -1 : rows.findIndex((row) => rowKeyOf(row) === sessionKey);
+    const rowIndex = rowIndexRaw === -1 ? 0 : rowIndexRaw;
+    const selectedRow = rows[rowIndex] ?? null;
+    const selectedGroup = selectedRow?.group ?? null;
+    // A worktree header still names a concrete conversation for session verbs:
+    // the newest live member, else the newest at all.
+    const selectedSession = selectedRow === null
+        ? null
+        : selectedRow.kind === "session"
+            ? selectedRow.item
+            : (selectedRow.group.sessions.find((item) => LIVE_STATUSES.has(item.session.status)) ??
+                selectedRow.group.sessions[0] ??
+                null);
     const pickerItems = picker === null ? [] : deriveHarnesses(picker.session);
+    const selectSession = (id) => setSessionKey(`s:${id}`);
     const say = (text) => setStatus({ text, at: Date.now() });
     const refetch = () => void queryClient.invalidateQueries({ queryKey: WORKBENCH_KEY });
     // Keep each pane's selection on screen — the one imperative escape hatch.
@@ -264,17 +204,19 @@ const App = ({ ctx, onQuit }) => {
         keepRowVisible(projectScrollRef.current, projectIndex);
     }, [projectIndex]);
     useEffect(() => {
-        // Rows are worktree groups (a session line plus its service children), so
-        // the scroll target is the group's y offset, not its index.
+        // Rows vary in height (header = 1; a session row carries its process and
+        // service fact lines), so the scroll target is the row's y offset.
+        const rowHeight = (row) => row === undefined || row.kind === "worktree"
+            ? 1
+            : 1 + row.item.processes.length + row.item.services.length;
         let top = 0;
-        for (const [index, item] of sessionItems.entries()) {
-            if (index === sessionIndex)
+        for (const [index, row] of rows.entries()) {
+            if (index === rowIndex)
                 break;
-            top += 1 + item.services.length;
+            top += rowHeight(row);
         }
-        const selectedHeight = 1 + (sessionItems[sessionIndex]?.services.length ?? 0);
-        keepSpanVisible(sessionScrollRef.current, top, selectedHeight);
-    }, [sessionIndex, sessionItems]);
+        keepSpanVisible(sessionScrollRef.current, top, rowHeight(rows[rowIndex]));
+    }, [rowIndex, rows]);
     const attachFlow = async (session) => {
         const short = session.id.slice(0, 8);
         lockRef.current = true;
@@ -359,7 +301,7 @@ const App = ({ ctx, onQuit }) => {
                 summary: null,
                 createdAt: new Date().toISOString(),
             }));
-            setSessionKey(vars.pendingKey);
+            selectSession(vars.pendingKey);
             setBusy(`provisioning ${vars.harness} workspace — a first launch builds the harness image ·`);
             setBusyStarted(Date.now());
         },
@@ -370,7 +312,7 @@ const App = ({ ctx, onQuit }) => {
         },
         onSuccess: async (session, vars) => {
             patchWorkbench((current) => replaceSession(current, vars.projectId, vars.pendingKey, session));
-            setSessionKey(session.id);
+            selectSession(session.id);
             setBusy(null);
             await attachIfIdle(session);
         },
@@ -383,7 +325,7 @@ const App = ({ ctx, onQuit }) => {
         onMutate: async (vars) => {
             await queryClient.cancelQueries({ queryKey: WORKBENCH_KEY });
             patchWorkbench((current) => mapWorkbenchSessions(current, (session) => session.id === vars.session.id ? { ...session, status: "starting" } : session));
-            setSessionKey(vars.session.id);
+            selectSession(vars.session.id);
             setBusy(`resuming ${vars.session.id.slice(0, 8)} — a fresh workspace restores the saved state ·`);
             setBusyStarted(Date.now());
         },
@@ -394,7 +336,7 @@ const App = ({ ctx, onQuit }) => {
         },
         onSuccess: async (resumed, vars) => {
             patchWorkbench((current) => replaceSession(current, vars.projectId, vars.session.id, resumed));
-            setSessionKey(resumed.id);
+            selectSession(resumed.id);
             setBusy(null);
             await attachIfIdle(resumed);
         },
@@ -424,7 +366,7 @@ const App = ({ ctx, onQuit }) => {
         onMutate: async (session) => {
             await queryClient.cancelQueries({ queryKey: WORKBENCH_KEY });
             patchWorkbench((current) => mapWorkbenchSessions(current, (row) => row.id === session.id ? { ...row, status: "stopped" } : row));
-            say(`stopped · ${worktreeName(session.branch)} — the record and review remain`);
+            say(`stopped · ${worktreeDisplayName(session)} — the record and review remain`);
         },
         onError: (error) => {
             say(errorText(error));
@@ -432,7 +374,109 @@ const App = ({ ctx, onQuit }) => {
         },
         onSettled: settleRefetch,
     });
+    // A new conversation inside an existing worktree — the `s` key's flow.
+    const launchInWorktreeMutation = useMutation({
+        mutationFn: async (vars) => {
+            const argv = HARNESS_COMMANDS[vars.harness];
+            if (argv === undefined)
+                throw new Error(`unknown harness "${vars.harness}"`);
+            const session = await ctx.api("POST", `/worktrees/${vars.worktreeId}/sessions`, {
+                harness: vars.harness,
+                label: null,
+            });
+            await ctx.api("POST", `/sessions/${session.id}/launch`, { argv });
+            return session;
+        },
+        onMutate: async (vars) => {
+            await queryClient.cancelQueries({ queryKey: WORKBENCH_KEY });
+            patchWorkbench((current) => prependSession(current, vars.projectId, {
+                id: vars.pendingKey,
+                worktreeId: vars.worktreeId,
+                harness: vars.harness,
+                label: null,
+                branch: "joining…",
+                baseSha: "",
+                baseRef: null,
+                status: "starting",
+                summary: null,
+                createdAt: new Date().toISOString(),
+            }));
+            selectSession(vars.pendingKey);
+            setBusy(`starting ${vars.harness} in the worktree ·`);
+            setBusyStarted(Date.now());
+        },
+        onError: (error, vars) => {
+            patchWorkbench((current) => removeSession(current, vars.projectId, vars.pendingKey));
+            setBusy(null);
+            say(errorText(error));
+        },
+        onSuccess: async (session, vars) => {
+            patchWorkbench((current) => replaceSession(current, vars.projectId, vars.pendingKey, session));
+            selectSession(session.id);
+            setBusy(null);
+            await attachIfIdle(session);
+        },
+        onSettled: settleRefetch,
+    });
+    // The one explicit destructive act. Against a pre-worktree server the
+    // session delete IS the old combined removal — same key, old semantics.
+    const removeWorktreeMutation = useMutation({
+        mutationFn: (group) => group.id !== null
+            ? ctx.api("DELETE", `/worktrees/${group.id}`)
+            : ctx.api("DELETE", `/sessions/${group.sessions[0]?.session.id ?? ""}`),
+        onMutate: (group) => {
+            say(`removing worktree · ${group.name}`);
+        },
+        onError: (error) => {
+            say(errorText(error));
+            refetch();
+        },
+        onSuccess: (_result, group) => {
+            say(`removed · ${group.name}`);
+            refetch();
+        },
+        onSettled: settleRefetch,
+    });
+    /** Worktree removal is armed like stops: the first press states the facts. */
+    const [removeArmed, setRemoveArmed] = useState(null);
+    const armRemove = () => {
+        const group = selectedGroup;
+        if (group === null || group.sessions.some((item) => isPendingId(item.session.id)))
+            return;
+        if (group.live > 0) {
+            say(`${group.live} session${group.live === 1 ? "" : "s"} live — stop them first · ${group.name}`);
+            return;
+        }
+        if (removeArmed === group.key) {
+            setRemoveArmed(null);
+            removeWorktreeMutation.mutate(group);
+            return;
+        }
+        setRemoveArmed(group.key);
+        const facts = group.sessions.length === 1
+            ? "its session and change go with it"
+            : `${group.sessions.length} sessions and the change go with it`;
+        say(`press again to remove worktree · ${group.name} — ${facts}`);
+    };
     const armStop = () => {
+        // A worktree header arms a stop of EVERY live conversation in it.
+        if (selectedRow?.kind === "worktree") {
+            const group = selectedRow.group;
+            const live = group.sessions.filter((item) => LIVE_STATUSES.has(item.session.status));
+            if (live.length === 0) {
+                say("nothing to stop — the worktree is settled");
+                return;
+            }
+            if (stopArmed === `wt:${group.key}`) {
+                setStopArmed(null);
+                for (const item of live)
+                    stopMutation.mutate(item.session);
+                return;
+            }
+            setStopArmed(`wt:${group.key}`);
+            say(`press again to stop ${live.length} live session${live.length === 1 ? "" : "s"} · ${group.name}`);
+            return;
+        }
         const item = selectedSession;
         if (item === null || isPendingId(item.session.id))
             return;
@@ -446,7 +490,7 @@ const App = ({ ctx, onQuit }) => {
             return;
         }
         setStopArmed(item.session.id);
-        say(`press again to stop · ${worktreeName(item.session.branch)}`);
+        say(`press again to stop · ${worktreeDisplayName(item.session)}`);
     };
     const startSession = (projectId, harness) => {
         setFocus("sessions");
@@ -469,8 +513,8 @@ const App = ({ ctx, onQuit }) => {
         const label = value.trim() === "" ? null : value.trim();
         renameMutation.mutate({ session, label });
     };
-    const openPicker = (session) => {
-        setPicker({ session });
+    const openPicker = (session, worktree) => {
+        setPicker(worktree === undefined ? { session } : { session, worktree });
         setPickerIndex(0);
     };
     const moveSelection = (delta) => {
@@ -489,12 +533,12 @@ const App = ({ ctx, onQuit }) => {
             }
             return;
         }
-        if (sessionItems.length === 0)
+        if (rows.length === 0)
             return;
-        const next = Math.max(0, Math.min(sessionItems.length - 1, sessionIndex + delta));
-        const item = sessionItems[next];
-        if (item !== undefined)
-            setSessionKey(item.session.id);
+        const next = Math.max(0, Math.min(rows.length - 1, rowIndex + delta));
+        const row = rows[next];
+        if (row !== undefined)
+            setSessionKey(rowKeyOf(row));
     };
     const activate = () => {
         if (picker !== null) {
@@ -503,7 +547,18 @@ const App = ({ ctx, onQuit }) => {
             if (choice === undefined || projectId === undefined)
                 return;
             setPicker(null);
-            if (picker.session === null) {
+            if (picker.worktree !== undefined && picker.worktree.id !== null) {
+                if (choice.harness !== null) {
+                    setFocus("sessions");
+                    launchInWorktreeMutation.mutate({
+                        projectId,
+                        worktreeId: picker.worktree.id,
+                        harness: choice.harness,
+                        pendingKey: pendingId(),
+                    });
+                }
+            }
+            else if (picker.session === null) {
                 if (choice.harness !== null)
                     startSession(projectId, choice.harness);
             }
@@ -516,6 +571,18 @@ const App = ({ ctx, onQuit }) => {
             setFocus("sessions");
             return;
         }
+        if (selectedRow?.kind === "worktree") {
+            // Enter on the place: attach its newest live conversation, or open a
+            // new one when nothing is live.
+            const live = selectedRow.group.sessions.find((item) => LIVE_STATUSES.has(item.session.status));
+            if (live !== undefined) {
+                void attachFlow(live.session);
+            }
+            else if (selectedRow.group.id !== null) {
+                openPicker(null, selectedRow.group);
+            }
+            return;
+        }
         const item = selectedSession;
         if (item === null)
             return;
@@ -571,6 +638,9 @@ const App = ({ ctx, onQuit }) => {
         // vim-up; the shift is the deliberateness the arm-confirm then doubles.
         if (key.shift === true && key.name === "k")
             return armStop();
+        // Shift+D: remove the selected worktree — the one explicit destructive act.
+        if (key.shift === true && key.name === "d")
+            return armRemove();
         switch (key.name) {
             case "q":
                 return onQuit();
@@ -606,6 +676,18 @@ const App = ({ ctx, onQuit }) => {
                 if (selectedProject !== null)
                     setNaming({ projectId: selectedProject.project.id });
                 return;
+            case "s": {
+                // A new conversation inside the selected worktree.
+                const group = selectedGroup;
+                if (group === null)
+                    return;
+                if (group.id === null) {
+                    say("this server predates shared worktrees — n starts a new one");
+                    return;
+                }
+                openPicker(null, group);
+                return;
+            }
             case "e": {
                 const item = selectedSession;
                 if (item !== null && !isPendingId(item.session.id))
@@ -628,7 +710,7 @@ const App = ({ ctx, onQuit }) => {
                     say("still provisioning — nothing to review yet");
                     return;
                 }
-                const target = reviewTargetForSession(item.session, item.annotation, selectedProject?.project.name ?? "project");
+                const target = reviewTargetForSession(item.session, selectedGroup?.annotation ?? item.annotation, selectedProject?.project.name ?? "project");
                 if (target === null) {
                     say("this session has no reviewable change yet");
                     return;
@@ -650,14 +732,16 @@ const App = ({ ctx, onQuit }) => {
     const sessionsTitle = selectedProject === null
         ? "sessions"
         : `sessions — ${selectedProject.project.name}${selectedProject.live > 0 ? ` · ${selectedProject.live} live` : ""}`;
-    const detailTitle = selectedSession === null
+    const detailTitle = selectedSession === null || selectedGroup === null
         ? "session"
-        : `worktree — ${worktreeName(selectedSession.session.branch)} · ${selectedSession.session.harness} ${selectedSession.session.id.slice(0, 8)}`;
+        : `worktree — ${selectedGroup.name} · ${selectedSession.session.harness} ${selectedSession.session.id.slice(0, 8)}`;
     const pickerTitle = picker === null
         ? ""
-        : picker.session === null
-            ? "new session — pick a harness"
-            : `resume ${picker.session.id.slice(0, 8)} — pick a harness`;
+        : picker.worktree !== undefined
+            ? `new session in ${picker.worktree.name} — pick a harness`
+            : picker.session === null
+                ? "new session — pick a harness"
+                : `resume ${picker.session.id.slice(0, 8)} — pick a harness`;
     const footerText = editing !== null
         ? " enter save · esc cancel"
         : naming !== null
@@ -666,7 +750,7 @@ const App = ({ ctx, onQuit }) => {
                 ? " ↑↓ move · enter start · esc cancel"
                 : focus === "projects"
                     ? " ↑↓ move · enter/l sessions · ⇥ panes · r refresh · q quit"
-                    : " ↑↓ move · enter attach/resume · n new · x stop · v review · e rename · o web · h/⇥ projects · q quit";
+                    : " ↑↓ move · enter attach/resume · n new worktree · s session here · x stop · ⇧D remove · v review · e rename · o web · q quit";
     const loadFailure = data === undefined && failureReason !== null
         ? failureReason instanceof Error
             ? failureReason.message
@@ -678,7 +762,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: [sessionItems.map((item, index) => (_jsx(SessionRow, { item: item, selected: index === sessionIndex }, item.session.id))), data !== undefined && sessionItems.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)))) })) : naming !== null ? (_jsx("box", { border: true, borderStyle: "rounded", borderColor: COBALT, title: " new worktree \u2014 name ", titleAlignment: "left", backgroundColor: "transparent", height: 3, flexShrink: 0, children: _jsx("input", { focused: true, value: "", placeholder: "name the worktree, e.g. fix-auth (empty = auto)", 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"] })] }), _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)))) })) : naming !== null ? (_jsx("box", { border: true, borderStyle: "rounded", borderColor: COBALT, title: " new worktree \u2014 name ", titleAlignment: "left", backgroundColor: "transparent", height: 3, flexShrink: 0, children: _jsx("input", { focused: true, value: "", placeholder: "name the worktree, e.g. fix-auth (empty = auto)", backgroundColor: "transparent", focusedBackgroundColor: "transparent", textColor: INK, focusedTextColor: INK, placeholderColor: FAINT, cursorColor: INK, flexGrow: 1, onSubmit: (value) => {
                         if (typeof value === "string")
                             submitWorktreeName(value);
                     } }) })) : 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) => {

package/dist/main.js

@@ -11,7 +11,7 @@ import { formatLoadReport } from "./env.js";
 import { loginCommand } from "./login.js";
 import { pairCommand, qrCommand } from "./pair.js";
 import { isComposeFile, proposeFromCompose, proposeFromPackageJson, proposeFromWorkspacePackage, renderMendToml, workspaceGlobs, } from "./service-init.js";
-import { agentIsLive, agentOutcome, cwdFacts, gitTopLevel, HARNESS_COMMANDS, isDetachChunk, LIVE_STATUSES, matchProjectByCwd, normalizeProjectName, parseLaunchArgs, } from "./shared.js";
+import { agentIsLive, agentOutcome, cwdFacts, gitTopLevel, HARNESS_COMMANDS, isDetachChunk, LIVE_STATUSES, sessionDisplayName, matchProjectByCwd, normalizeProjectName, parseLaunchArgs, } from "./shared.js";
 import { sshCommand } from "./ssh-setup.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).
@@ -284,7 +284,37 @@ const launch = async (config, harness, args) => {
     say(`${green("✓")} project ${project.name} ${dim(`· ${project.defaultBranch}${parsed.project === null ? " · from cwd" : ""}`)}`);
     // The worktree's name comes first, then the session details — it is the
     // identity every list leads with. `mend run` stays scriptable: flag only.
-    const worktreeName = harness === "run" ? parsed.name : (parsed.name ?? (await askWorktreeName()));
+    // `--worktree` insists on joining: the name must already exist here.
+    let worktreeName;
+    if (parsed.worktree !== null) {
+        const detail = await api(config, "GET", `/projects/${project.id}`);
+        const existing = detail.worktrees ?? [];
+        if (detail.worktrees === undefined) {
+            return fail("this server predates shared worktrees — use --name instead");
+        }
+        const match = existing.find((worktree) => worktree.name === parsed.worktree) ??
+            (existing.filter((worktree) => worktree.name.startsWith(parsed.worktree ?? "")).length === 1
+                ? existing.find((worktree) => worktree.name.startsWith(parsed.worktree ?? ""))
+                : undefined);
+        if (match === undefined) {
+            const names = existing.map((worktree) => worktree.name).join(", ");
+            return fail(`no worktree matches "${parsed.worktree}" in ${project.name}${names === "" ? "" : ` — have: ${names}`}`);
+        }
+        worktreeName = match.name;
+    }
+    else {
+        worktreeName = harness === "run" ? parsed.name : (parsed.name ?? (await askWorktreeName()));
+    }
+    // Say when the name joins an existing worktree — a join is a fact worth
+    // stating before the session exists, not a surprise in the tree later.
+    if (worktreeName !== null) {
+        const detail = await api(config, "GET", `/projects/${project.id}`).catch(() => null);
+        const joined = detail?.worktrees?.find((worktree) => worktree.name === worktreeName);
+        if (joined !== undefined) {
+            const members = (detail?.sessions ?? []).filter((candidate) => candidate.worktreeId === joined.id).length;
+            say(`${green("✓")} joins worktree ${joined.name} ${dim(`· ${members} session${members === 1 ? "" : "s"} · branch ${joined.branch}`)}`);
+        }
+    }
     const lifecycle = harness === "run"
         ? "background"
         : parsed.detach
@@ -593,7 +623,7 @@ 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.branch} · ${match.harness} ${dim(match.id.slice(0, 8))}${detachHint()}`);
+    say(`${green("✓")} attaching to ${sessionDisplayName(match)} · ${match.harness} ${dim(match.id.slice(0, 8))}${detachHint()}`);
     say("");
     await attachOrExit(config, match.id, match.harness);
     exitAfterSessionEnd(config, match.id);
@@ -2067,7 +2097,7 @@ const rejoinCommand = async (config, args) => {
     if (session === undefined)
         return fail("session selection failed");
     const alreadyLive = agentLiveIn(detail, session);
-    say(`${green("✓")} rejoining ${session.branch} · ${session.harness} ${dim(session.id.slice(0, 8))} · ${alreadyLive ? "already live" : "restoring"}`);
+    say(`${green("✓")} rejoining ${sessionDisplayName(session)} · ${session.harness} ${dim(session.id.slice(0, 8))} · ${alreadyLive ? "already live" : "restoring"}`);
     say(`${cobalt("  watch")} · ${config.url}/sessions/${session.id}`);
     let restored = false;
     const currentAgent = detail.annotations.find((annotation) => annotation.sessionId === session.id)?.currentAgent ??
@@ -2168,6 +2198,15 @@ const printSessionRow = (row) => {
  */
 const sessionsCommand = async (config, args) => {
     const all = args.includes("--all");
+    // v1 stays byte-stable for pinned integrations; v2 is the worktree envelope.
+    if (args.includes("--json=v2")) {
+        const projectFlag = args.indexOf("--project");
+        const projectName = projectFlag !== -1 && args[projectFlag + 1] !== undefined
+            ? String(args[projectFlag + 1])
+            : null;
+        say(JSON.stringify(await buildWorktreesJson(config, projectName), null, 2));
+        return;
+    }
     const json = args.includes("--json");
     const projectFlag = args.indexOf("--project");
     const projectName = projectFlag !== -1 && args[projectFlag + 1] !== undefined
@@ -2243,6 +2282,117 @@ const sessionsCommand = async (config, args) => {
     for (const row of rows)
         printSessionRow(row);
 };
+/**
+ * The worktree-grouped view both `mend worktrees --json` and
+ * `mend sessions --json=v2` emit. Against a pre-worktree server every session
+ * becomes its own pseudo worktree (`id: null`) — the envelope shape is stable
+ * either way, so integrations pin on `version`, not server age.
+ */
+const toWorktreeJsonSession = (session) => ({
+    id: session.id,
+    harness: session.harness,
+    label: session.label,
+    status: session.status,
+    summary: session.summary,
+    createdAt: session.createdAt,
+});
+const buildWorktreesJson = async (config, projectName) => {
+    const projects = await api(config, "GET", "/projects");
+    const scope = projectName === null ? projects : projects.filter((p) => p.name === projectName);
+    const details = await Promise.all(scope.map((p) => api(config, "GET", `/projects/${p.id}`)));
+    const worktrees = [];
+    for (const detail of details) {
+        const reviewOf = (sessionIds) => {
+            const facts = detail.annotations.find((a) => sessionIds.has(a.sessionId));
+            return facts === undefined
+                ? null
+                : {
+                    openComments: facts.openComments,
+                    totalComments: facts.totalComments,
+                    pendingFollowUp: detail.annotations.some((a) => sessionIds.has(a.sessionId) && a.pendingFollowUp),
+                };
+        };
+        const urlOf = (sessionIds) => {
+            const first = [...sessionIds][0];
+            return first === undefined ? null : `${config.url.replace(/\/$/, "")}/sessions/${first}`;
+        };
+        if (detail.worktrees !== undefined) {
+            for (const worktree of detail.worktrees) {
+                const members = detail.sessions.filter((session) => session.worktreeId === worktree.id);
+                const ids = new Set(members.map((session) => session.id));
+                worktrees.push({
+                    id: worktree.id,
+                    name: worktree.name,
+                    projectId: detail.project.id,
+                    projectName: detail.project.name,
+                    branch: worktree.branch,
+                    baseSha: worktree.baseSha,
+                    baseRef: worktree.baseRef,
+                    createdAt: worktree.createdAt,
+                    reviewUrl: urlOf(ids),
+                    review: reviewOf(ids),
+                    sessions: members
+                        .toSorted((a, b) => b.createdAt.localeCompare(a.createdAt))
+                        .map(toWorktreeJsonSession),
+                });
+            }
+        }
+        else {
+            for (const session of detail.sessions) {
+                const ids = new Set([session.id]);
+                worktrees.push({
+                    id: null,
+                    name: session.worktree,
+                    projectId: detail.project.id,
+                    projectName: detail.project.name,
+                    branch: session.branch,
+                    baseSha: session.baseSha,
+                    baseRef: session.baseRef,
+                    createdAt: session.createdAt,
+                    reviewUrl: urlOf(ids),
+                    review: reviewOf(ids),
+                    sessions: [toWorktreeJsonSession(session)],
+                });
+            }
+        }
+    }
+    return { version: 2, worktrees };
+};
+/** `mend worktrees [--project <p>] [--json]` — the container-first listing. */
+const worktreesCommand = async (config, args) => {
+    const json = args.includes("--json");
+    const projectFlag = args.indexOf("--project");
+    const projectName = projectFlag !== -1 && args[projectFlag + 1] !== undefined
+        ? String(args[projectFlag + 1])
+        : null;
+    const payload = await buildWorktreesJson(config, projectName);
+    if (json) {
+        say(JSON.stringify(payload, null, 2));
+        return;
+    }
+    if (payload.worktrees.length === 0) {
+        say(dim("no worktrees yet — mend claude --name <worktree> starts one"));
+        return;
+    }
+    for (const worktree of payload.worktrees) {
+        const live = worktree.sessions.filter((session) => ACTIVE_STATUSES.has(session.status)).length;
+        const facts = [
+            `${worktree.sessions.length} session${worktree.sessions.length === 1 ? "" : "s"}`,
+        ];
+        if (live > 0)
+            facts.push(green(`${live} live`));
+        if (worktree.review !== null && worktree.review.openComments > 0) {
+            facts.push(amber(`${worktree.review.openComments} open`));
+        }
+        const base = worktree.baseRef ?? worktree.baseSha.slice(0, 12);
+        say(`${worktree.name.padEnd(24)}  ${worktree.projectName}  ${dim(`${worktree.branch} · base ${base}`)}  ${facts.join(dim(" · "))}`);
+        for (const session of worktree.sessions) {
+            const status = session.status.padEnd(9);
+            const name = session.label ?? `session ${session.id.slice(0, 8)}`;
+            say(`  └ ${session.harness.padEnd(8)}  ${dim(session.id.slice(0, 8))}  ${ACTIVE_STATUSES.has(session.status) ? green(status) : dim(status)}  ${name}`);
+        }
+    }
+};
 // ─── dashboard: the live TUI on bare `mend` ─────────────────────────────────
 const hasNodeFfi = () => {
     try {
@@ -2295,11 +2445,13 @@ start
   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 codex|claude|opencode ["prompt"] [--name <worktree>] [--model <id>]
-                             [--effort low|medium|high|xhigh|max]
+  mend codex|claude|opencode ["prompt"] [--name <worktree>] [--worktree <existing>]
+                             [--model <id>] [--effort low|medium|high|xhigh|max]
                              [--base <ref>] [--ask] [--fast] [--detach|-d] [--foreground]
-                                        new session worktree + launch the harness in it; the
-                                        worktree's name is asked first (--name skips the ask), a
+                                        launch the harness in a worktree; the worktree's name is
+                                        asked first (--name skips the ask — an EXISTING name joins
+                                        that worktree as a new session; --worktree joins only,
+                                        failing if absent), a
                                         quoted prompt becomes its first message,
                                         --ask restores the harness's permission prompts, --fast
                                         requests priority processing (codex service tier),
@@ -2325,6 +2477,9 @@ everything else
   mend keys share                       relay THIS machine's ssh-agent to the server (bridge mode:
                                         hardware keys sign here; Ctrl-C stops sharing)
   mend run -- <command...>              same, with an arbitrary command
+  mend worktrees [--project <p>] [--json]
+                                        every worktree and the sessions inside it (mend sessions
+                                        --json stays the v1 flat list; --json=v2 groups like this)
   mend attach <session-id-prefix>       reattach this terminal to a running session
   mend stop <session-id-prefix> | --all [--project <p>]
                                         stop the agent — the workspace harvests and closes; the
@@ -2421,6 +2576,8 @@ const main = async () => {
         case "sessions":
         case "status":
             return sessionsCommand(config, rest);
+        case "worktrees":
+            return worktreesCommand(config, rest);
         case undefined:
         case "ui":
             return dashboard(config);

package/dist/shared.js

@@ -35,6 +35,7 @@ const LAUNCH_ERROR = {
     effort: null,
     base: null,
     name: null,
+    worktree: null,
     ask: false,
     fast: false,
     detach: false,
@@ -58,6 +59,7 @@ export const parseLaunchArgs = (args) => {
     let effort = null;
     let base = null;
     let workName = null;
+    let joinWorktree = null;
     let ask = false;
     let fast = false;
     let detach = false;
@@ -84,7 +86,8 @@ export const parseLaunchArgs = (args) => {
             arg === "--model" ||
             arg === "--effort" ||
             arg === "--base" ||
-            arg === "--name") {
+            arg === "--name" ||
+            arg === "--worktree") {
             const value = flagArgs[index + 1];
             if (value === undefined)
                 return { ...LAUNCH_ERROR, error: `${arg} needs a value` };
@@ -96,6 +99,8 @@ export const parseLaunchArgs = (args) => {
                 effort = value;
             else if (arg === "--name")
                 workName = normalizeProjectName(value);
+            else if (arg === "--worktree")
+                joinWorktree = value;
             else
                 base = value;
             index += 1;
@@ -123,6 +128,12 @@ export const parseLaunchArgs = (args) => {
     if (detach && foreground) {
         return { ...LAUNCH_ERROR, error: "--detach and --foreground contradict — pick one" };
     }
+    if (workName !== null && joinWorktree !== null) {
+        return {
+            ...LAUNCH_ERROR,
+            error: "--name and --worktree contradict — --name names (or joins), --worktree only joins",
+        };
+    }
     return {
         project,
         prompt,
@@ -130,6 +141,7 @@ export const parseLaunchArgs = (args) => {
         effort,
         base,
         name: workName,
+        worktree: joinWorktree,
         ask,
         fast,
         detach,
@@ -161,6 +173,19 @@ export const isDetachChunk = (data) => {
     }
     return false;
 };
+/**
+ * What to call a session's worktree in banners and rows: a NAMED worktree is
+ * its branch minus the `mend/` prefix; an unnamed one (`mend/session/<uuid>`)
+ * is called by its auto-name label, or its short id before one lands.
+ */
+export const sessionDisplayName = (session) => {
+    if (session.branch.startsWith("mend/") && !session.branch.startsWith("mend/session/")) {
+        return session.branch.slice("mend/".length);
+    }
+    if (!session.branch.startsWith("mend/session/"))
+        return session.branch;
+    return session.label ?? `session ${session.id.slice(0, 8)}`;
+};
 export const LIVE_STATUSES = new Set([
     "starting",
     "running",

package/dist/workbench-events.js

@@ -55,6 +55,7 @@ export const eventFamilies = (payload) => {
         return [];
     switch (parsed.type) {
         case "project":
+        case "worktree":
         case "session-process":
             return ["workbench"];
         // Session facts feed both surfaces: rows and annotations on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/mend",
-  "version": "0.14.0",
+  "version": "0.15.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",