@sealant/mend 0.12.2 → 0.14.0

package/dist/dashboard.js

@@ -5,7 +5,7 @@ import { QueryClient, QueryClientProvider, useMutation, useQuery, useQueryClient
 import { useEffect, useRef, useState } from "react";
 import { reviewTargetForSession } from "./review-workflow.js";
 import { ReviewScreen } from "./review.js";
-import { cwdFacts, HARNESS_COMMANDS, isPendingId, LIVE_STATUSES, matchProjectByCwd, pendingId, } from "./shared.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";
@@ -138,11 +138,23 @@ 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] }) }));
+/**
+ * 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.
+ */
 const SessionRow = ({ item, selected, }) => {
-    const { session, annotation } = item;
+    const { session, annotation, services } = item;
     const color = STATUS_COLOR[session.status] ?? MUTED;
     const age = timeAgo(session.createdAt).replace(" ago", "");
-    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: session.harness.padEnd(9) }), _jsx("span", { fg: FAINT, children: session.id.slice(0, 8) }), _jsx("span", { fg: color, children: `  ${session.status.padEnd(10)}` }), _jsx("span", { fg: FAINT, children: age.padEnd(9) }), annotation !== undefined && annotation.openComments > 0 ? (_jsx("span", { fg: MUTED, children: `${annotation.openComments} open  ` })) : null, _jsx("span", { fg: MUTED, children: (session.label ?? "").slice(0, 40) })] }) }));
+    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 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 })] }) }));
 /**
@@ -183,15 +195,16 @@ const StatusLine = ({ busy, busyStarted, status, }) => {
 };
 const errorText = (error) => error instanceof Error ? error.message : String(error);
 /** Keep a 1-line-per-row selection inside its scrollbox's real viewport. */
-const keepRowVisible = (scroll, index) => {
+const keepSpanVisible = (scroll, top, height) => {
     if (scroll === null)
         return;
     const viewH = Math.max(1, scroll.viewport.height);
-    if (index < scroll.scrollTop)
-        scroll.scrollTo(index);
-    else if (index + 1 > scroll.scrollTop + viewH)
-        scroll.scrollTo(index + 1 - viewH);
+    if (top < scroll.scrollTop)
+        scroll.scrollTo(top);
+    else if (top + height > scroll.scrollTop + viewH)
+        scroll.scrollTo(top + height - viewH);
 };
+const keepRowVisible = (scroll, index) => keepSpanVisible(scroll, index, 1);
 const PROJECTS_PANE_WIDTH = 30;
 const App = ({ ctx, onQuit }) => {
     const renderer = useRenderer();
@@ -212,6 +225,11 @@ const App = ({ ctx, onQuit }) => {
     const [busyStarted, setBusyStarted] = useState(0);
     const [status, setStatus] = useState(null);
     const [editing, setEditing] = useState(null);
+    /** Session id a stop is armed against; the second press fires it. */
+    const [stopArmed, setStopArmed] = useState(null);
+    /** The new-session flow asks the worktree's name FIRST, then the harness. */
+    const [naming, setNaming] = useState(null);
+    const [pendingName, setPendingName] = useState(null);
     const [reviewing, setReviewing] = useState(null);
     /** Set synchronously around attach/launch so keystrokes can't double-fire. */
     const lockRef = useRef(false);
@@ -246,8 +264,17 @@ const App = ({ ctx, onQuit }) => {
         keepRowVisible(projectScrollRef.current, projectIndex);
     }, [projectIndex]);
     useEffect(() => {
-        keepRowVisible(sessionScrollRef.current, sessionIndex);
-    }, [sessionIndex]);
+        // Rows are worktree groups (a session line plus its service children), so
+        // the scroll target is the group's y offset, not its index.
+        let top = 0;
+        for (const [index, item] of sessionItems.entries()) {
+            if (index === sessionIndex)
+                break;
+            top += 1 + item.services.length;
+        }
+        const selectedHeight = 1 + (sessionItems[sessionIndex]?.services.length ?? 0);
+        keepSpanVisible(sessionScrollRef.current, top, selectedHeight);
+    }, [sessionIndex, sessionItems]);
     const attachFlow = async (session) => {
         const short = session.id.slice(0, 8);
         lockRef.current = true;
@@ -275,9 +302,11 @@ const App = ({ ctx, onQuit }) => {
         }
         say(outcome === "unavailable"
             ? "attach unavailable — could not connect"
-            : outcome === "detached"
+            : outcome === "detached" || outcome === "interrupted"
                 ? `detached — ${short} keeps running`
-                : `session settled · ${short}`);
+                : outcome === "dropped"
+                    ? `disconnected — ${short} keeps running`
+                    : `session settled · ${short}`);
         refetch();
     };
     /** Converge on the server's truth once, after the LAST in-flight mutation. */
@@ -311,6 +340,7 @@ const App = ({ ctx, onQuit }) => {
             const session = await ctx.api("POST", `/projects/${vars.projectId}/sessions`, {
                 harness: vars.harness,
                 label: null,
+                name: vars.name,
                 base: null,
             });
             await ctx.api("POST", `/sessions/${session.id}/launch`, { argv });
@@ -322,7 +352,7 @@ const App = ({ ctx, onQuit }) => {
                 id: vars.pendingKey,
                 harness: vars.harness,
                 label: null,
-                branch: "provisioning…",
+                branch: vars.name === null ? "provisioning…" : `mend/${vars.name}`,
                 baseSha: "",
                 baseRef: null,
                 status: "starting",
@@ -387,9 +417,48 @@ const App = ({ ctx, onQuit }) => {
         },
         onSettled: settleRefetch,
     });
+    // Stops are explicit — and armed: the first press names what a second press
+    // will stop; moving the selection re-arms against the newly selected row.
+    const stopMutation = useMutation({
+        mutationFn: (session) => ctx.api("POST", `/sessions/${session.id}/stop`),
+        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`);
+        },
+        onError: (error) => {
+            say(errorText(error));
+            refetch();
+        },
+        onSettled: settleRefetch,
+    });
+    const armStop = () => {
+        const item = selectedSession;
+        if (item === null || isPendingId(item.session.id))
+            return;
+        if (!LIVE_STATUSES.has(item.session.status)) {
+            say("nothing to stop — the session is settled");
+            return;
+        }
+        if (stopArmed === item.session.id) {
+            setStopArmed(null);
+            stopMutation.mutate(item.session);
+            return;
+        }
+        setStopArmed(item.session.id);
+        say(`press again to stop · ${worktreeName(item.session.branch)}`);
+    };
     const startSession = (projectId, harness) => {
         setFocus("sessions");
-        launchMutation.mutate({ projectId, harness, pendingKey: pendingId() });
+        launchMutation.mutate({ projectId, harness, name: pendingName, pendingKey: pendingId() });
+        setPendingName(null);
+    };
+    /** Name first, then the harness: the worktree is the identity being created. */
+    const submitWorktreeName = (value) => {
+        setNaming(null);
+        const slug = normalizeProjectName(value.trim());
+        setPendingName(value.trim() === "" ? null : slug);
+        openPicker(null);
     };
     const resumeSession = (projectId, session, harness) => {
         setFocus("sessions");
@@ -473,6 +542,11 @@ const App = ({ ctx, onQuit }) => {
                 setEditing(null);
             return;
         }
+        if (naming !== null) {
+            if (key.name === "escape")
+                setNaming(null);
+            return;
+        }
         if (picker !== null) {
             switch (key.name) {
                 case "down":
@@ -493,6 +567,10 @@ const App = ({ ctx, onQuit }) => {
                     return;
             }
         }
+        // Shift+K (and x below): stop the selected session. Lowercase k stays
+        // vim-up; the shift is the deliberateness the arm-confirm then doubles.
+        if (key.shift === true && key.name === "k")
+            return armStop();
         switch (key.name) {
             case "q":
                 return onQuit();
@@ -502,6 +580,8 @@ const App = ({ ctx, onQuit }) => {
             case "up":
             case "k":
                 return moveSelection(-1);
+            case "x":
+                return armStop();
             case "return":
             case "linefeed":
                 return activate();
@@ -522,8 +602,9 @@ const App = ({ ctx, onQuit }) => {
                     setFocus(focus === "projects" ? "sessions" : "projects");
                 return;
             case "n":
+                // The worktree's name comes first; the harness picker follows.
                 if (selectedProject !== null)
-                    openPicker(null);
+                    setNaming({ projectId: selectedProject.project.id });
                 return;
             case "e": {
                 const item = selectedSession;
@@ -571,7 +652,7 @@ const App = ({ ctx, onQuit }) => {
         : `sessions — ${selectedProject.project.name}${selectedProject.live > 0 ? ` · ${selectedProject.live} live` : ""}`;
     const detailTitle = selectedSession === null
         ? "session"
-        : `session — ${selectedSession.session.harness} ${selectedSession.session.id.slice(0, 8)}`;
+        : `worktree — ${worktreeName(selectedSession.session.branch)} · ${selectedSession.session.harness} ${selectedSession.session.id.slice(0, 8)}`;
     const pickerTitle = picker === null
         ? ""
         : picker.session === null
@@ -579,11 +660,13 @@ const App = ({ ctx, onQuit }) => {
             : `resume ${picker.session.id.slice(0, 8)} — pick a harness`;
     const footerText = editing !== null
         ? " enter save · esc cancel"
-        : picker !== null
-            ? " ↑↓ move · enter start · esc cancel"
-            : focus === "projects"
-                ? " ↑↓ move · enter/l sessions · ⇥ panes · r refresh · q quit"
-                : " ↑↓ move · enter attach/resume · n new · v review · e rename · o web · h/⇥ projects · q quit";
+        : naming !== null
+            ? " enter continue — the harness picker follows · esc cancel"
+            : picker !== null
+                ? " ↑↓ 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";
     const loadFailure = data === undefined && failureReason !== null
         ? failureReason instanceof Error
             ? failureReason.message
@@ -595,7 +678,10 @@ 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)))) })) : 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"] })] }), _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) => {
+                        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) => {
                         if (typeof value === "string")
                             submitRename(editing, value);
                     } }) })) : showDetail ? (_jsx(Pane, { title: detailTitle, focused: false, height: 6, children: _jsx(SessionDetail, { item: selectedSession }) })) : null, _jsx(StatusLine, { busy: busy, busyStarted: busyStarted, status: status }), _jsx("text", { height: 1, fg: FAINT, bg: "transparent", children: footerText })] }));

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, LIVE_STATUSES, matchProjectByCwd, normalizeProjectName, parseLaunchArgs, } from "./shared.js";
+import { agentIsLive, agentOutcome, cwdFacts, gitTopLevel, HARNESS_COMMANDS, isDetachChunk, LIVE_STATUSES, 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).
@@ -227,6 +227,38 @@ const findProject = async (config, explicit, adoptCwd = false) => {
     say(`${green("✓")} adopted · ${adopted.name} · ${dim(adopted.storePath)}`);
     return adopted;
 };
+/**
+ * Cascade for the launch lifecycle: per-launch flag → project stance → global
+ * setting. Any read failure (an older server, a blip) stays background — a
+ * network hiccup must never flip launch semantics to foreground.
+ */
+const resolvedBackgroundSessions = async (config, project) => {
+    if (project.backgroundSessions === "on")
+        return true;
+    if (project.backgroundSessions === "off")
+        return false;
+    try {
+        const settings = await request(config, "GET", "/settings");
+        return settings.backgroundSessions !== false;
+    }
+    catch {
+        return true;
+    }
+};
+/** One-line TTY ask: the worktree's name comes first — it is the identity being created. */
+const askWorktreeName = async () => {
+    if (process.stdin.isTTY !== true || process.stdout.isTTY !== true)
+        return null;
+    const readline = await import("node:readline/promises");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`  worktree name ${dim("(enter for auto)")}: `)).trim();
+        return answer === "" ? null : normalizeProjectName(answer);
+    }
+    finally {
+        rl.close();
+    }
+};
 const launch = async (config, harness, args) => {
     const parsed = parseLaunchArgs(args);
     if (parsed.error !== null)
@@ -239,6 +271,9 @@ const launch = async (config, harness, args) => {
     if (harness === "run" && structured) {
         return fail("mend run takes no prompt or harness flags — usage: mend run [--project p] -- <command...>");
     }
+    if (harness === "run" && (parsed.detach || parsed.foreground)) {
+        return fail("mend run takes no lifecycle flags — it tails the record; Ctrl+C stops watching, not the command");
+    }
     const argv = harness === "run" ? parsed.custom : (HARNESS_COMMANDS[harness] ?? []);
     if (argv.length === 0) {
         return fail(harness === "run" ? "usage: mend run -- <command...>" : `unknown harness ${harness}`);
@@ -247,11 +282,42 @@ const launch = async (config, harness, args) => {
     // Say which project the cwd resolved to before anything is created — a
     // wrong guess should be visible here, not discovered in the tree later.
     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()));
+    const lifecycle = harness === "run"
+        ? "background"
+        : parsed.detach
+            ? "detach"
+            : parsed.foreground
+                ? "foreground"
+                : (await resolvedBackgroundSessions(config, project))
+                    ? "background"
+                    : "foreground";
+    // Foreground holds from the moment the session exists: a signal between
+    // create and attach stops it too. attachTty owns signals while attached.
+    let createdSessionId = null;
+    let attachOwnsSignals = false;
+    const onLaunchSignal = () => {
+        if (attachOwnsSignals)
+            return;
+        const id = createdSessionId;
+        if (id === null)
+            process.exit(1);
+        void stopSessionQuickly(config, id).then((stopped) => process.exit(stopped ? 0 : 1));
+    };
+    if (lifecycle === "foreground") {
+        for (const signal of ["SIGHUP", "SIGINT", "SIGTERM"]) {
+            process.on(signal, onLaunchSignal);
+        }
+    }
     const session = await api(config, "POST", `/projects/${project.id}/sessions`, {
         harness,
         label: null,
+        name: worktreeName,
         base: parsed.base,
     });
+    createdSessionId = session.id;
     say(`${green("✓")} worktree ${session.worktree} ${dim(`· branch ${session.branch}`)}`);
     const baseWord = session.baseRef === null ? "" : `${session.baseRef} `;
     say(`${green("✓")} base ${baseWord}${dim(session.baseSha.slice(0, 12))} · session ${dim(session.id.slice(0, 8))}`);
@@ -274,12 +340,17 @@ const launch = async (config, harness, args) => {
         }
         : { argv };
     await withSpinner("provisioning workspace — a first launch builds the harness image (can take minutes)…", api(config, "POST", `/sessions/${session.id}/launch`, launchBody));
+    if (lifecycle === "detach") {
+        say(`${green("✓ recording")} · running detached`);
+        say(`${cobalt("  attach")} · mend attach ${session.id.slice(0, 8)}`);
+        return;
+    }
     say(`${green("✓ recording")} · workspace mounts the worktree${detachHint()}`);
     say("");
-    await attachOrExit(config, session.id, session.harness);
+    attachOwnsSignals = true;
+    await attachOrExit(config, session.id, session.harness, lifecycle);
     exitAfterSessionEnd(config, session.id);
 };
-// ─── the terminal bridge: raw stdin/stdout against the platform PTY ─────────
 /**
  * Attach this terminal to the session's PTY through the Mend server over ONE
  * WebSocket: binary frames are PTY bytes both ways, text frames carry control
@@ -288,7 +359,9 @@ const launch = async (config, harness, args) => {
  * Ctrl+] detaches — the session keeps running and can be reattached from
  * anywhere. Resolves when the session settles or the user detaches; the
  * caller decides what each outcome means (commands exit, the dashboard
- * resumes).
+ * resumes). With `handleSignals`, a terminal-window close (SIGHUP) or kill
+ * resolves `interrupted` through the same restore path instead of leaving
+ * raw mode pushed — the handler never exits the process itself.
  */
 const attachTty = async (config, sessionId, harness, from, processId, options) => {
     const url = parseMendUrl(`${config.url}/api/tty`);
@@ -336,6 +409,16 @@ const attachTty = async (config, sessionId, harness, from, processId, options) =
     const rawTty = process.stdin.isTTY === true;
     let rawModeEnabled = false;
     let detached = false;
+    let sawEnd = false;
+    let interrupted = false;
+    const onSignal = () => {
+        // Resolve the attach instead of exiting: the shared `finally` restores raw
+        // mode and closes the socket, then the caller decides what the signal means.
+        interrupted = true;
+        ws.close();
+        finishAttachment?.();
+    };
+    const signals = ["SIGHUP", "SIGINT", "SIGTERM"];
     const onTtyFrame = (event) => {
         if (typeof event.data !== "string") {
             process.stdout.write(Buffer.from(event.data));
@@ -349,6 +432,7 @@ const attachTty = async (config, sessionId, harness, from, processId, options) =
             // Session lifecycle is authoritative. Start detaching immediately instead
             // of holding the user's terminal for the later close handshake and Mend's
             // settle/checkpoint/harvest work.
+            sawEnd = true;
             ws.close();
             finishAttachment?.();
         }
@@ -357,8 +441,10 @@ const attachTty = async (config, sessionId, harness, from, processId, options) =
         }
     };
     const onKeys = (data) => {
-        if (detachKeyEnabled && data.includes(0x1d)) {
-            // Ctrl+] — detach, leave the session running.
+        if (detachKeyEnabled && isDetachChunk(data)) {
+            // Ctrl+] — detach, leave the session running. Matched in both its
+            // encodings: the inner TUI may have switched the user's terminal onto
+            // the kitty keyboard protocol, where the key arrives as CSI-u.
             detached = true;
             ws.close();
             return;
@@ -371,6 +457,9 @@ const attachTty = async (config, sessionId, harness, from, processId, options) =
     try {
         sendResize();
         process.stdout.on("resize", onWinch);
+        if (options?.handleSignals === true)
+            for (const signal of signals)
+                process.on(signal, onSignal);
         // Read-only (logs): never forward stdin — Ctrl+C exits the CLI, the
         // socket drops, and the process inside keeps running untouched.
         if (options?.readOnly !== true) {
@@ -383,33 +472,111 @@ const attachTty = async (config, sessionId, harness, from, processId, options) =
         }
         ws.addEventListener("message", onTtyFrame);
         await finished;
-        return detached ? "detached" : "ended";
+        return detached ? "detached" : interrupted ? "interrupted" : sawEnd ? "ended" : "dropped";
     }
     finally {
+        for (const signal of signals)
+            process.off(signal, onSignal);
         process.stdin.off("data", onKeys);
         process.stdout.off("resize", onWinch);
         ws.removeEventListener("message", onTtyFrame);
         ws.removeEventListener("close", onClose);
         if (rawModeEnabled)
             process.stdin.setRawMode(false);
+        if (options?.readOnly !== true && process.stdout.isTTY === true) {
+            // The inner TUI's terminal modes leaked onto OUR terminal through the
+            // byte bridge — kitty keyboard protocol, bracketed paste, mouse
+            // reporting, alternate screen, hidden cursor. The TUI keeps running
+            // remotely; the local terminal must come back to shell sanity, or every
+            // keystroke after a detach arrives as CSI-u junk. A reattach replays
+            // the session from 0, which re-establishes whatever the TUI had set.
+            process.stdout.write("\x1b[<u\x1b[=0;1u" + // pop the kitty keyboard stack, then force flags 0
+                "\x1b[?2004l" + // bracketed paste off
+                "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l" + // mouse reporting off
+                "\x1b[?1049l" + // leave the alternate screen (no-op when already left)
+                "\x1b[?25h");
+        }
         process.stdin.pause();
         if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)
             ws.close();
         stopHerdrHint();
     }
 };
-/** How every one-shot command handles an attach outcome: detach says so, settle returns. */
-const finishAttach = (config, sessionId, outcome) => {
+/**
+ * Best-effort stop under a signal's short grace window — a SIGHUP handler
+ * cannot afford the ordinary retry path. True when the server accepted.
+ */
+const stopSessionQuickly = async (config, sessionId) => {
+    const headers = { "content-type": "application/json" };
+    if (config.token !== null)
+        headers["authorization"] = `Bearer ${config.token}`;
+    try {
+        const response = await fetch(`${config.url}/api/sessions/${sessionId}/stop`, {
+            method: "POST",
+            headers,
+            signal: AbortSignal.timeout(2500),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+};
+/** Foreground exit: stop the session, or say honestly that it may still run. */
+const stopAndExit = async (config, sessionId) => {
+    const id8 = sessionId.slice(0, 8);
+    if (await stopSessionQuickly(config, sessionId)) {
+        say(`${green("✓")} stopped · ${id8}`);
+        say(`${cobalt("  review")} · ${config.url}/sessions/${sessionId}`);
+        process.exit(0);
+    }
+    say(`${amber("could not stop")} — the session may still run · mend stop ${id8}`);
+    process.exit(1);
+};
+/**
+ * How every one-shot command handles an attach outcome: detach says so and
+ * always leaves the session running; a signal or a dropped socket answers to
+ * the lifecycle mode; a settled session returns so the caller prints its facts.
+ */
+const finishAttach = async (config, sessionId, outcome, mode = "background") => {
+    const id8 = sessionId.slice(0, 8);
     if (outcome === "unavailable") {
         return fail(`tty attach unavailable: could not connect to ${config.url}`);
     }
     if (outcome === "detached") {
         say("");
-        say(`${amber("detached")} — the session keeps running; reattach: mend attach ${sessionId.slice(0, 8)}`);
+        say(`${amber("detached")} — the session keeps running; reattach: mend attach ${id8}`);
+        process.exit(0);
+    }
+    if (outcome === "interrupted") {
+        say("");
+        if (mode === "foreground")
+            return stopAndExit(config, sessionId);
+        say(`${amber("detached")} — the session keeps running; reattach: mend attach ${id8}`);
+        process.exit(0);
+    }
+    if (outcome === "dropped") {
+        say("");
+        if (mode === "foreground") {
+            // The drop may be the server settling the session — verify before stopping.
+            let live;
+            try {
+                const detail = await request(config, "GET", `/sessions/${sessionId}`);
+                live = agentIsLive(detail.session, detail.currentAgent);
+            }
+            catch {
+                say(`${amber("could not stop")} — the session may still run · mend stop ${id8}`);
+                process.exit(1);
+            }
+            if (!live)
+                return; // settled as the socket closed — the caller prints the end facts
+            return stopAndExit(config, sessionId);
+        }
+        say(`${amber("disconnected")} — the session keeps running; reattach: mend attach ${id8}`);
         process.exit(0);
     }
 };
-const attachOrExit = async (config, sessionId, harness) => finishAttach(config, sessionId, await attachTty(config, sessionId, harness, 0n));
+const attachOrExit = async (config, sessionId, harness, mode = "background") => finishAttach(config, sessionId, await attachTty(config, sessionId, harness, 0n, undefined, { handleSignals: true }), mode);
 /** Return terminal control as soon as the terminal reports the observed end. */
 const exitAfterSessionEnd = (config, sessionId) => {
     say("");
@@ -426,11 +593,61 @@ const attach = async (config, args) => {
     const match = sessions.find((s) => s.id.startsWith(prefix));
     if (match === undefined)
         return fail(`no active session matches "${prefix}"`);
-    say(`${green("✓")} attaching to ${match.harness} · ${dim(match.id.slice(0, 8))}${detachHint()}`);
+    say(`${green("✓")} attaching to ${match.branch} · ${match.harness} ${dim(match.id.slice(0, 8))}${detachHint()}`);
     say("");
     await attachOrExit(config, match.id, match.harness);
     exitAfterSessionEnd(config, match.id);
 };
+/**
+ * Explicit stop — the one intent detaching never carries. Ends the agent; the
+ * workspace harvests and closes; the record and review remain.
+ */
+const stopCommand = async (config, args) => {
+    const all = args.includes("--all");
+    const projectFlag = args.indexOf("--project");
+    const projectName = projectFlag !== -1 && args[projectFlag + 1] !== undefined
+        ? String(args[projectFlag + 1])
+        : null;
+    const prefix = args.find((arg, index) => !arg.startsWith("--") && index !== projectFlag + 1);
+    if (!all && prefix === undefined) {
+        return fail("usage: mend stop <session-id-prefix> | --all [--project <p>]");
+    }
+    const [sessions, projects] = await Promise.all([
+        api(config, "GET", "/sessions"),
+        api(config, "GET", "/projects"),
+    ]);
+    let scoped = sessions;
+    if (projectName !== null) {
+        const project = projects.find((p) => p.name === projectName);
+        if (project === undefined)
+            return fail(`no project named "${projectName}"`);
+        scoped = sessions.filter((s) => s.projectId === project.id);
+    }
+    let targets;
+    if (all) {
+        targets = scoped;
+        if (targets.length === 0) {
+            say("no active sessions");
+            return;
+        }
+    }
+    else {
+        const matches = scoped.filter((s) => s.id.startsWith(prefix ?? ""));
+        if (matches.length === 0)
+            return fail(`no active session matches "${prefix}"`);
+        if (matches.length > 1) {
+            return fail(`session prefix "${prefix}" is ambiguous — use more of the id`);
+        }
+        targets = matches;
+    }
+    for (const session of targets) {
+        await api(config, "POST", `/sessions/${session.id}/stop`);
+        say(`${green("✓")} stopped · ${session.harness} · ${dim(session.id.slice(0, 8))} · ${session.branch}`);
+        say(`${cobalt("  review")} · ${config.url}/sessions/${session.id}`);
+    }
+    if (all)
+        say(`${green("✓")} stopped ${targets.length} session${targets.length === 1 ? "" : "s"}`);
+};
 /** Compact picker: numbered live sessions, one keystroke of typing. */
 const pickSessionInteractively = async (rows) => {
     say(dim("more than one live session — pick one:"));
@@ -493,12 +710,14 @@ const shellCommand = async (config, args) => {
     say(`${green("✓")} shell in ${session.harness} session ${dim(session.id.slice(0, 8))} · ${dim(session.branch)}${detachHint()}`);
     const shellProcess = await withSpinner("opening a shell in the session workspace…", api(config, "POST", `/sessions/${session.id}/shell`));
     say("");
-    const outcome = await attachTty(config, session.id, "shell", 0n, shellProcess.id);
+    const outcome = await attachTty(config, session.id, "shell", 0n, shellProcess.id, {
+        handleSignals: true,
+    });
     if (outcome === "unavailable") {
         return fail(`tty attach unavailable: could not connect to ${config.url}`);
     }
     say("");
-    if (outcome === "detached") {
+    if (outcome === "detached" || outcome === "interrupted" || outcome === "dropped") {
         say(`${amber("detached")} — the shell keeps running and holds the workspace open`);
         process.exit(0);
     }
@@ -1571,7 +1790,8 @@ _mend() {
     'adopt:adopt a repository into the store'
     'codex:new session + codex' 'claude:new session + claude' 'opencode:new session + opencode'
     'run:new session + arbitrary command'
-    'attach:reattach to a running session' 'shell:open a shell in a live session workspace'
+    'attach:reattach to a running session' 'stop:stop the agent — record and review remain'
+    'shell:open a shell in a live session workspace'
     'service:reachable ports — add, list, stop'
     'keys:the machine Mend deploy key — init, show, share'
     'accounts:your connected accounts on the platform'
@@ -1587,7 +1807,7 @@ _mend() {
     return
   fi
   case $words[2] in
-    shell|attach|continue|resume|rejoin)
+    shell|attach|stop|continue|resume|rejoin)
       local -a sessions
       sessions=(\${(f)"$(command mend __complete session 2>/dev/null | tr '\\t' ':')"})
       (( \${#sessions} )) && _describe 'session' sessions
@@ -1599,11 +1819,11 @@ _mend "$@"
 const BASH_COMPLETIONS = `_mend() {
   local cur=\${COMP_WORDS[COMP_CWORD]}
   if [ "$COMP_CWORD" -eq 1 ]; then
-    COMPREPLY=( $(compgen -W "adopt codex claude opencode run attach shell service keys pair doctor continue resume rejoin refresh projects sessions status ui help" -- "$cur") )
+    COMPREPLY=( $(compgen -W "adopt codex claude opencode run attach stop shell service keys pair doctor continue resume rejoin refresh projects sessions status ui help" -- "$cur") )
     return
   fi
   case \${COMP_WORDS[1]} in
-    shell|attach|continue|resume|rejoin)
+    shell|attach|stop|continue|resume|rejoin)
       COMPREPLY=( $(compgen -W "$(command mend __complete session 2>/dev/null | cut -f1)" -- "$cur") )
       ;;
   esac
@@ -1782,7 +2002,17 @@ const resumeCommand = async (config, args) => {
     }
     say(`${green("✓")} resuming ${match.harness} · ${dim(match.id.slice(0, 8))}${withHarness === null ? "" : ` ${dim("as")} ${withHarness}`}`);
     say(`${cobalt("  watch")} · ${config.url}/sessions/${match.id}`);
-    await withSpinner("resuming — a fresh workspace restores the saved session state…", api(config, "POST", `/sessions/${match.id}/resume`, { harness: withHarness }));
+    // A formerly-protocol session (a phone pickup) resumed from a terminal must
+    // come back as a TUI — the handoff verb routes it there; a plain resume
+    // would re-enter protocol mode with nothing to attach.
+    const priorAgent = detail.annotations.find((annotation) => annotation.sessionId === match.id)?.currentAgent ??
+        null;
+    const protocolPrior = priorAgent?.kind === "agent-protocol" && withHarness === null;
+    await withSpinner(protocolPrior
+        ? "reopening as a terminal — same conversation…"
+        : "resuming — a fresh workspace restores the saved session state…", protocolPrior
+        ? api(config, "POST", `/sessions/${match.id}/handoff`, { to: "pty" })
+        : api(config, "POST", `/sessions/${match.id}/resume`, { harness: withHarness }));
     say(`${green("✓ recording")} · same worktree, conversation restored${detachHint()}`);
     say("");
     await attachOrExit(config, match.id, withHarness ?? match.harness);
@@ -1837,25 +2067,40 @@ const rejoinCommand = async (config, args) => {
     if (session === undefined)
         return fail("session selection failed");
     const alreadyLive = agentLiveIn(detail, session);
-    say(`${green("✓")} rejoining ${session.harness} · ${dim(session.id.slice(0, 8))} · ${alreadyLive ? "already live" : "restoring"}`);
+    say(`${green("✓")} rejoining ${session.branch} · ${session.harness} ${dim(session.id.slice(0, 8))} · ${alreadyLive ? "already live" : "restoring"}`);
     say(`${cobalt("  watch")} · ${config.url}/sessions/${session.id}`);
     let restored = false;
-    if (!alreadyLive) {
+    const currentAgent = detail.annotations.find((annotation) => annotation.sessionId === session.id)?.currentAgent ??
+        null;
+    if (currentAgent?.kind === "agent-protocol") {
+        // A protocol agent (a phone pickup) has no PTY to attach. Hand the session
+        // off to a terminal: the TUI resumes the same provider conversation, with
+        // the phone-authored turns in its scrollback.
+        await withSpinner(alreadyLive
+            ? "taking over from the protocol session — same conversation…"
+            : "reopening as a terminal — same conversation…", api(config, "POST", `/sessions/${session.id}/handoff`, { to: "pty" }));
+        restored = true;
+    }
+    else if (!alreadyLive) {
         restored = await resumeForRejoin(config, session.id, "resuming — a fresh workspace restores the saved session state…");
     }
     say(restored
         ? `${green("✓ recording")} · same worktree, conversation restored${detachHint()}`
         : `${green("✓ recording")} · attached to the live session${detachHint()}`);
     say("");
-    let outcome = await attachTty(config, session.id, session.harness, 0n);
+    let outcome = await attachTty(config, session.id, session.harness, 0n, undefined, {
+        handleSignals: true,
+    });
     if (outcome === "unavailable") {
         const refreshed = await api(config, "GET", `/sessions/${session.id}`);
         if (!agentIsLive(refreshed.session, refreshed.currentAgent)) {
             await resumeForRejoin(config, session.id, "session settled while attaching — restoring it once…");
         }
-        outcome = await attachTty(config, session.id, session.harness, 0n);
+        outcome = await attachTty(config, session.id, session.harness, 0n, undefined, {
+            handleSignals: true,
+        });
     }
-    finishAttach(config, session.id, outcome);
+    await finishAttach(config, session.id, outcome);
     exitAfterSessionEnd(config, session.id);
 };
 // ─── projects · sessions: the workbench at a glance ─────────────────────────
@@ -2050,12 +2295,16 @@ 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"] [--model <id>] [--effort low|medium|high|xhigh|max]
-                             [--base <ref>] [--ask] [--fast]
-                                        new session worktree + launch the harness in it; a quoted
-                                        prompt becomes its first message (and names the session),
+  mend codex|claude|opencode ["prompt"] [--name <worktree>] [--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
+                                        quoted prompt becomes its first message,
                                         --ask restores the harness's permission prompts, --fast
-                                        requests priority processing (codex service tier)
+                                        requests priority processing (codex service tier),
+                                        --detach launches without attaching (reattach anywhere),
+                                        --foreground stops the session when this CLI exits
   mend pair [--url <base url>]          pair a phone or a second machine: prints a QR, the code, and
                                         the URL to reach this server (one device, once, 10 minutes)
   mend doctor                           read-only checklist of this machine's setup — one line per
@@ -2077,6 +2326,9 @@ everything else
                                         hardware keys sign here; Ctrl-C stops sharing)
   mend run -- <command...>              same, with an arbitrary command
   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
+                                        record and review remain
   mend shell [session-id-prefix]        open a shell in a live session's workspace
   mend service run [session] --port <p> [--name <n>] [--udp] -- <command...>
                                         start + supervise a server in the session workspace
@@ -2123,6 +2375,8 @@ const main = async () => {
             return launch(config, command, rest);
         case "attach":
             return attach(config, rest);
+        case "stop":
+            return stopCommand(config, rest);
         case "shell":
             return shellCommand(config, rest);
         case "service":

package/dist/shared.js

@@ -34,13 +34,17 @@ const LAUNCH_ERROR = {
     model: null,
     effort: null,
     base: null,
+    name: null,
     ask: false,
     fast: false,
+    detach: false,
+    foreground: false,
     custom: [],
 };
 /**
  * `mend claude|codex|opencode ["prompt"] [--model <id>] [--effort <level>]
- * [--base <ref>] [--ask] [--project <p>]`, plus `mend run … -- <command...>`.
+ * [--base <ref>] [--ask] [--detach|-d] [--foreground] [--project <p>]`, plus
+ * `mend run … -- <command...>`.
  * The first non-flag positional is the prompt; a second one is an error so a
  * forgotten quote fails loudly instead of launching with half a sentence.
  */
@@ -53,8 +57,11 @@ export const parseLaunchArgs = (args) => {
     let model = null;
     let effort = null;
     let base = null;
+    let workName = null;
     let ask = false;
     let fast = false;
+    let detach = false;
+    let foreground = false;
     for (let index = 0; index < flagArgs.length; index += 1) {
         const arg = flagArgs[index] ?? "";
         if (arg === "--ask") {
@@ -65,7 +72,19 @@ export const parseLaunchArgs = (args) => {
             fast = true;
             continue;
         }
-        if (arg === "--project" || arg === "--model" || arg === "--effort" || arg === "--base") {
+        if (arg === "--detach" || arg === "-d") {
+            detach = true;
+            continue;
+        }
+        if (arg === "--foreground") {
+            foreground = true;
+            continue;
+        }
+        if (arg === "--project" ||
+            arg === "--model" ||
+            arg === "--effort" ||
+            arg === "--base" ||
+            arg === "--name") {
             const value = flagArgs[index + 1];
             if (value === undefined)
                 return { ...LAUNCH_ERROR, error: `${arg} needs a value` };
@@ -75,6 +94,8 @@ export const parseLaunchArgs = (args) => {
                 model = value;
             else if (arg === "--effort")
                 effort = value;
+            else if (arg === "--name")
+                workName = normalizeProjectName(value);
             else
                 base = value;
             index += 1;
@@ -99,7 +120,46 @@ export const parseLaunchArgs = (args) => {
     if (effort !== null && !EFFORT_LEVELS.includes(effort)) {
         return { ...LAUNCH_ERROR, error: `--effort must be one of ${EFFORT_LEVELS.join(", ")}` };
     }
-    return { project, prompt, model, effort, base, ask, fast, custom, error: null };
+    if (detach && foreground) {
+        return { ...LAUNCH_ERROR, error: "--detach and --foreground contradict — pick one" };
+    }
+    return {
+        project,
+        prompt,
+        model,
+        effort,
+        base,
+        name: workName,
+        ask,
+        fast,
+        detach,
+        foreground,
+        custom,
+        error: null,
+    };
+};
+/**
+ * Whether a raw stdin chunk carries the detach key (Ctrl+]). Two encodings
+ * reach us: the legacy control byte 0x1d — and, once an inner TUI (claude)
+ * pushes the kitty keyboard protocol through the PTY and the user's own
+ * terminal honors it, the CSI-u escape `ESC [ 93 ; 5 u` (`]` is code 93,
+ * ctrl is modifier 5), optionally with a kitty event-type suffix. Only press
+ * (`:1`) and repeat (`:2`) are intent; a release (`:3`) is not.
+ */
+export const isDetachChunk = (data) => {
+    if (data.includes(0x1d))
+        return true;
+    // latin1 maps bytes 1:1, so the scan sees exactly the wire bytes. A string
+    // scan rather than a regex: an escape byte inside a pattern trips lint, and
+    // anchoring on the real ESC[ prefix keeps pasted text from ever matching.
+    const text = data.toString("latin1");
+    const prefix = "\u001b[93;5";
+    for (let start = text.indexOf(prefix); start !== -1; start = text.indexOf(prefix, start + 1)) {
+        const rest = text.slice(start + prefix.length);
+        if (rest.startsWith("u") || rest.startsWith(":1u") || rest.startsWith(":2u"))
+            return true;
+    }
+    return false;
 };
 export const LIVE_STATUSES = new Set([
     "starting",

package/package.json

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