@sealant/mend 0.12.2 → 0.13.0

package/dist/dashboard.js

@@ -275,9 +275,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. */

package/dist/main.js

@@ -227,6 +227,24 @@ 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;
+    }
+};
 const launch = async (config, harness, args) => {
     const parsed = parseLaunchArgs(args);
     if (parsed.error !== null)
@@ -239,6 +257,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 +268,38 @@ 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" : ""}`)}`);
+    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,
         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 +322,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 +341,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 +391,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 +414,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?.();
         }
@@ -371,6 +437,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,9 +452,11 @@ 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);
@@ -398,18 +469,81 @@ const attachTty = async (config, sessionId, harness, from, processId, options) =
         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("");
@@ -431,6 +565,56 @@ const attach = async (config, args) => {
     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 +677,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 +1757,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 +1774,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 +1786,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 +1969,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);
@@ -1840,22 +2037,37 @@ const rejoinCommand = async (config, args) => {
     say(`${green("✓")} rejoining ${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 ─────────────────────────
@@ -2051,11 +2263,13 @@ start
                                         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]
+                             [--base <ref>] [--ask] [--fast] [--detach|-d] [--foreground]
                                         new session worktree + launch the harness in it; a quoted
                                         prompt becomes its first message (and names the session),
                                         --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 +2291,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 +2340,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

@@ -36,11 +36,14 @@ const LAUNCH_ERROR = {
     base: 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.
  */
@@ -55,6 +58,8 @@ export const parseLaunchArgs = (args) => {
     let base = 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,6 +70,14 @@ export const parseLaunchArgs = (args) => {
             fast = true;
             continue;
         }
+        if (arg === "--detach" || arg === "-d") {
+            detach = true;
+            continue;
+        }
+        if (arg === "--foreground") {
+            foreground = true;
+            continue;
+        }
         if (arg === "--project" || arg === "--model" || arg === "--effort" || arg === "--base") {
             const value = flagArgs[index + 1];
             if (value === undefined)
@@ -99,7 +112,22 @@ 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,
+        ask,
+        fast,
+        detach,
+        foreground,
+        custom,
+        error: null,
+    };
 };
 export const LIVE_STATUSES = new Set([
     "starting",

package/package.json

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