@sealant/mend 0.1.1 → 0.2.0

package/README.md

@@ -33,12 +33,12 @@ mend status                           active sessions (alias of mend sessions)
 
 ## Configuration
 
-| Source             | What                                              |
-| ------------------ | ------------------------------------------------- |
-| `MEND_URL`         | The Mend server (default `http://localhost:3105`) |
-| `MEND_TOKEN`       | Bearer token for that server                      |
-| `MEND_DETACH_KEY`  | Set to `none` when an outer multiplexer detaches  |
-| `~/.mend/cli.json` | `{ "url": ..., "token": ... }` — env vars win     |
+| Source                    | What                                                                                      |
+| ------------------------- | ----------------------------------------------------------------------------------------- |
+| `MEND_URL`                | The Mend server (default `http://localhost:3105`)                                         |
+| `MEND_TOKEN`              | Bearer token for that server                                                              |
+| `MEND_DETACH_KEY`         | Set to `none` when an outer multiplexer detaches                                          |
+| `~/.config/mend/cli.json` | `{ "url": ..., "token": ... }` — env vars win; a pre-XDG `~/.mend/cli.json` keeps working |
 
 ## Herdr
 

package/dist/dashboard.js

@@ -43,8 +43,21 @@ const timeAgo = (iso) => {
 const WORKBENCH_KEY = ["workbench"];
 const fetchWorkbench = async (ctx) => {
     const projects = await ctx.api("GET", "/projects");
-    const fetched = await Promise.all(projects.map((project) => ctx.api("GET", `/projects/${project.id}`)));
-    return { projects, details: new Map(fetched.map((detail) => [detail.project.id, detail])) };
+    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,
+    };
 };
 const itemKey = (item) => item.kind === "session"
     ? item.session.id
@@ -84,6 +97,7 @@ const deriveItems = (view, data) => {
             kind: "session",
             session,
             annotation: detail.annotations.find((a) => a.sessionId === session.id),
+            services: data.servicesBySession.get(session.id) ?? [],
         }));
     }
     const resuming = view.session;
@@ -100,7 +114,9 @@ const deriveItems = (view, data) => {
                 kind: "harness",
                 harness,
                 label: harness,
-                hint: "the conversation crosses as a distilled prompt",
+                hint: harness === "shell"
+                    ? "a bash in the worktree — resume either agent from inside"
+                    : "the conversation crosses as a distilled prompt",
             })),
         ];
     }
@@ -108,7 +124,9 @@ const deriveItems = (view, data) => {
         kind: "harness",
         harness,
         label: harness,
-        hint: `mend ${harness} — new worktree, recorded session`,
+        hint: harness === "shell"
+            ? "a plain bash session — new worktree, recorded"
+            : `mend ${harness} — new worktree, recorded session`,
     }));
 };
 // ─── rows: JSX spans instead of StyledText chunks ───────────────────────────
@@ -122,13 +140,20 @@ const Facts = ({ facts }) => {
         _jsxs("span", { children: [index > 0 ? _jsx("span", { fg: FAINT, children: " \u00B7 " }) : null, fact] }, index))) }));
 };
 const SessionRow = ({ item, selected, }) => {
-    const { session, annotation } = item;
+    const { session, annotation, services } = item;
     const color = STATUS_COLOR[session.status] ?? MUTED;
     const glyph = STATUS_GLYPH[session.status] ?? "·";
     const facts = [];
     const age = timeAgo(session.createdAt);
     if (age !== "")
         facts.push(_jsx("span", { fg: FAINT, children: age }));
+    // What runs right now: name :port → host port, observed state colored.
+    for (const service of services.slice(0, 2)) {
+        facts.push(_jsx("span", { fg: service.status === "reachable" ? GREEN : AMBER, children: `${service.label ?? service.id.slice(0, 6)} :${service.workspacePort ?? "?"}${service.protocol === "udp" ? "u" : ""}→${service.hostPort ?? "?"} ${service.status}` }));
+    }
+    if (services.length > 2) {
+        facts.push(_jsx("span", { fg: FAINT, children: `+${services.length - 2} services` }));
+    }
     if (session.label !== null)
         facts.push(_jsx("span", { fg: MUTED, children: session.label }));
     if (annotation !== undefined && annotation.openComments > 0) {

package/dist/dotfiles.js

@@ -0,0 +1,90 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Local dotfiles scanning for `mend dotfiles sync`. This runs on the machine that HAS the
+ * files — the whole point: the Mend server may be a VPS whose home directory is a service
+ * account's, so contents are captured here and streamed to the server's per-user dotfiles store.
+ *
+ * The candidate list mirrors the product's curated set (plain configuration only — never keys,
+ * credential stores, or histories). The CLI stays dependency-light by design, so the list is
+ * duplicated here rather than imported from a workspace package.
+ */
+export const DOTFILE_CANDIDATES = [
+    {
+        group: "shell",
+        paths: [
+            ".zshrc",
+            ".zshenv",
+            ".zprofile",
+            ".bashrc",
+            ".bash_profile",
+            ".profile",
+            ".aliases",
+            ".config/fish/config.fish",
+            ".config/starship.toml",
+        ],
+    },
+    {
+        group: "git",
+        paths: [".gitconfig", ".gitignore_global", ".config/git/config", ".config/git/ignore"],
+    },
+    {
+        group: "editors",
+        paths: [".vimrc", ".ideavimrc", ".editorconfig", ".config/helix/config.toml"],
+    },
+    {
+        group: "terminal",
+        paths: [".tmux.conf", ".config/tmux/tmux.conf", ".inputrc", ".dir_colors"],
+    },
+    {
+        group: "tools",
+        paths: [
+            ".ripgreprc",
+            ".config/bat/config",
+            ".config/lazygit/config.yml",
+            ".config/mise/config.toml",
+            ".config/atuin/config.toml",
+            ".config/zellij/config.kdl",
+        ],
+    },
+];
+/** The per-file cap the server enforces; checked here so a mistake fails before the upload. */
+export const MAX_FILE_BYTES = 1024 * 1024;
+const statFile = (home, relative) => {
+    try {
+        const stat = fs.statSync(path.join(home, relative));
+        return stat.isFile() ? stat : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** Probe the curated candidates under `home`; only existing regular files appear. */
+export const scanDotfileCandidates = (home) => DOTFILE_CANDIDATES.flatMap(({ group, paths }) => paths.flatMap((relative) => {
+    const stat = statFile(home, relative);
+    return stat === null ? [] : [{ path: relative, group, bytes: stat.size }];
+}));
+/**
+ * Read the selected paths for upload. Explicitly requested paths must exist (a typo should fail,
+ * not silently sync nothing); oversized files fail with the server's own rule. Modes ride along
+ * so an executable script stays executable.
+ */
+export const readSyncFiles = (home, paths_) => {
+    const files = [];
+    for (const relative of paths_) {
+        const stat = statFile(home, relative);
+        if (stat === null) {
+            return { error: `${relative} is not a file under ${home}` };
+        }
+        if (stat.size > MAX_FILE_BYTES) {
+            return { error: `${relative} is over 1MB — dotfiles are text; trim the selection` };
+        }
+        files.push({
+            path: relative,
+            contentsBase64: fs.readFileSync(path.join(home, relative)).toString("base64"),
+            // eslint-disable-next-line no-bitwise -- permission bits are the point
+            mode: (stat.mode & 0o777).toString(8),
+        });
+    }
+    return { files };
+};

package/dist/main.js

@@ -2,10 +2,21 @@
 import { spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import { createRequire } from "node:module";
+import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
+import { readSyncFiles, scanDotfileCandidates } from "./dotfiles.js";
+import { isComposeFile, proposeFromCompose, proposeFromPackageJson, proposeFromWorkspacePackage, renderMendToml, workspaceGlobs, } from "./service-init.js";
 import { CONTINUE_COMMANDS, gitTopLevel, HARNESS_COMMANDS, LIVE_STATUSES, matchProjectByCwd, normalizeProjectName, } from "./shared.js";
-const CONFIG_PATH = path.join(os.homedir(), ".mend", "cli.json");
+// `$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).
+const mendCliHome = () => {
+    const xdg = process.env["XDG_CONFIG_HOME"];
+    const preferred = path.join(xdg === undefined || xdg === "" ? path.join(os.homedir(), ".config") : xdg, "mend");
+    const legacy = path.join(os.homedir(), ".mend");
+    return !fs.existsSync(preferred) && fs.existsSync(legacy) ? legacy : preferred;
+};
+const CONFIG_PATH = path.join(mendCliHome(), "cli.json");
 const loadConfig = () => {
     let fileConfig = {};
     if (fs.existsSync(CONFIG_PATH)) {
@@ -132,18 +143,35 @@ const withSpinner = async (label, work) => {
 const adopt = async (config, args) => {
     const nameFlag = args.indexOf("--name");
     const name = nameFlag !== -1 && args[nameFlag + 1] !== undefined ? String(args[nameFlag + 1]) : null;
-    const positional = args.filter((a, i) => !a.startsWith("--") && (nameFlag === -1 || i !== nameFlag + 1));
+    const authFlagIndex = args.indexOf("--auth");
+    const positional = args.filter((a, i) => !a.startsWith("--") &&
+        (nameFlag === -1 || i !== nameFlag + 1) &&
+        (authFlagIndex === -1 || i !== authFlagIndex + 1));
     // Bare `mend adopt` adopts the repo the cwd is inside, not the subdirectory.
     const rawSource = positional[0] ?? gitTopLevel(process.cwd()) ?? ".";
     const source = /^(https?|git|ssh):|^git@/.test(rawSource) ? rawSource : path.resolve(rawSource);
     // Derived defaults are normalized ("Mend" → "mend"); explicit --name is sent as typed.
     const projectName = name ?? normalizeProjectName(path.basename(source, ".git"));
+    const auth = authFlagIndex !== -1 && args[authFlagIndex + 1] !== undefined
+        ? String(args[authFlagIndex + 1])
+        : null;
+    if (auth !== null && auth !== "ambient" && auth !== "mend-key" && auth !== "bridge") {
+        return fail(`--auth takes "ambient", "mend-key", or "bridge", not "${auth}"`);
+    }
     const project = await api(config, "POST", "/projects", {
         name: projectName,
         source,
+        ...(auth === null ? {} : { gitAuthMode: auth }),
     });
     say(`${green("✓")} adopted · ${project.name} · ${dim(project.storePath)}`);
     say(`${dim("  default branch")} ${project.defaultBranch}`);
+    // Say which signer did the work — the clone already proved it answers.
+    if (project.gitAuthMode === "mend-key") {
+        say(`${dim("  git auth")} mend key ${dim("(the machine's deploy key signed this clone)")}`);
+    }
+    else if (project.gitAuthMode === "bridge") {
+        say(`${dim("  git auth")} bridge ${dim("(signed through the connected `mend keys share`)")}`);
+    }
     say(`${dim("  sessions start with:")} mend codex ${dim("(from anywhere —")} --project ${project.name}${dim(")")}`);
 };
 // ─── session launch ─────────────────────────────────────────────────────────
@@ -218,10 +246,15 @@ const launch = async (config, harness, args) => {
  * caller decides what each outcome means (commands exit, the dashboard
  * resumes).
  */
-const attachTty = async (config, sessionId, harness, from) => {
+const attachTty = async (config, sessionId, harness, from, processId, options) => {
     const url = new URL(`${config.url}/api/tty`);
     url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-    url.searchParams.set("session", sessionId);
+    // Process addressing reaches any PTY in the workspace (a shell); the
+    // session form remains the agent's PTY.
+    if (processId !== undefined)
+        url.searchParams.set("process", processId);
+    else
+        url.searchParams.set("session", sessionId);
     url.searchParams.set("from", from.toString());
     if (config.token !== null)
         url.searchParams.set("token", config.token);
@@ -294,12 +327,16 @@ const attachTty = async (config, sessionId, harness, from) => {
     try {
         sendResize();
         process.stdout.on("resize", onWinch);
-        if (rawTty) {
-            process.stdin.setRawMode(true);
-            rawModeEnabled = true;
+        // 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) {
+            if (rawTty) {
+                process.stdin.setRawMode(true);
+                rawModeEnabled = true;
+            }
+            process.stdin.resume();
+            process.stdin.on("data", onKeys);
         }
-        process.stdin.resume();
-        process.stdin.on("data", onKeys);
         ws.addEventListener("message", onTtyFrame);
         await finished;
         return detached ? "detached" : "ended";
@@ -350,6 +387,702 @@ const attach = async (config, args) => {
     await attachOrExit(config, match.id, match.harness);
     exitAfterSessionEnd(config, match.id);
 };
+/** Compact picker: numbered live sessions, one keystroke of typing. */
+const pickSessionInteractively = async (rows) => {
+    say(dim("more than one live session — pick one:"));
+    rows.forEach((row, index) => {
+        say(`  ${index + 1}. ${row.session.harness.padEnd(8)} ${dim(row.session.id.slice(0, 8))}  ${row.projectName}  ${dim(row.session.branch)}`);
+    });
+    const readline = await import("node:readline/promises");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question("  session #: ");
+    rl.close();
+    const chosen = rows[Number(answer.trim()) - 1];
+    if (chosen === undefined)
+        return fail(`"${answer.trim()}" is not one of the choices`);
+    return chosen.session;
+};
+/**
+ * The resolution order (docs/SESSION-SERVICES.md): an explicit id wins, then
+ * the cwd's project narrows, one candidate is taken, several go to the
+ * picker, and a non-interactive caller never gets a silent guess.
+ */
+const resolveLiveSession = async (config, prefix) => {
+    const sessions = await api(config, "GET", "/sessions");
+    if (prefix !== undefined) {
+        const matches = sessions.filter((s) => s.id.startsWith(prefix));
+        if (matches.length === 0)
+            return fail(`no live session matches "${prefix}"`);
+        const exact = matches[0];
+        if (matches.length > 1 || exact === undefined) {
+            return fail(`session prefix "${prefix}" is ambiguous — use more of the id`);
+        }
+        return exact;
+    }
+    const projects = await api(config, "GET", "/projects");
+    const project = matchProjectByCwd(projects, process.cwd());
+    const candidates = project === undefined ? sessions : sessions.filter((s) => s.projectId === project.id);
+    const only = candidates[0];
+    if (only === undefined) {
+        return fail("no live session — start one with mend codex|claude|opencode");
+    }
+    if (candidates.length === 1)
+        return only;
+    if (process.stdin.isTTY !== true) {
+        return fail("several live sessions — name one: mend shell <session-id-prefix>");
+    }
+    const nameById = new Map(projects.map((p) => [p.id, p.name]));
+    return pickSessionInteractively(candidates.map((session) => ({
+        session,
+        projectName: nameById.get(session.projectId) ?? session.projectId.slice(0, 8),
+    })));
+};
+/**
+ * A real interactive shell in the session's CURRENT workspace — same
+ * /workspace/repo the agent is editing, same dependencies, same network. Not
+ * a shell in the host checkout. The shell holds a workspace lease, so the
+ * container survives the agent settling while the shell lives.
+ */
+const shellCommand = async (config, args) => {
+    const prefix = args.find((a) => !a.startsWith("--"));
+    const session = await resolveLiveSession(config, prefix);
+    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);
+    if (outcome === "unavailable") {
+        return fail(`tty attach unavailable: could not connect to ${config.url}`);
+    }
+    say("");
+    if (outcome === "detached") {
+        say(`${amber("detached")} — the shell keeps running and holds the workspace open`);
+        process.exit(0);
+    }
+    say(`${green("✓")} shell ended`);
+    process.exit(0);
+};
+const serviceUrl = (config, service) => {
+    const host = new URL(config.url).hostname || "localhost";
+    // A UDP Service has no page to open — the endpoint is the whole fact.
+    return service.protocol === "udp"
+        ? `${host}:${service.hostPort ?? "?"} (udp)`
+        : `http://${host}:${service.hostPort ?? "?"}`;
+};
+const printService = (config, service) => {
+    const status = service.status === "reachable" ? green(service.status) : amber(service.status);
+    say(`${(service.label ?? service.id.slice(0, 8)).padEnd(12)}  ${dim(`:${service.workspacePort ?? "?"}${service.protocol === "udp" ? "/udp" : ""} →`)} ${serviceUrl(config, service)}  ${status}  ${dim(service.id.slice(0, 8))}`);
+};
+/**
+ * Adopt an already-listening workspace port as a Service: Mend binds a host
+ * port on its private interfaces and pumps every connection into the
+ * session's workspace. No supervision — reachability is the observation.
+ */
+const serviceAdd = async (config, args) => {
+    const nameFlag = args.indexOf("--name");
+    const name = nameFlag !== -1 && args[nameFlag + 1] !== undefined ? String(args[nameFlag + 1]) : null;
+    const protocol = args.includes("--udp") ? "udp" : "tcp";
+    const positional = args.filter((a, i) => !a.startsWith("--") && (nameFlag === -1 || i !== nameFlag + 1));
+    const portRaw = positional.find((a) => /^\d+$/.test(a));
+    if (portRaw === undefined) {
+        return fail("usage: mend service add [session] <port> [--name <n>] [--udp]");
+    }
+    const port = Number(portRaw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return fail(`"${portRaw}" is not a port`);
+    }
+    const prefix = positional.find((a) => a !== portRaw);
+    const session = await resolveLiveSession(config, prefix);
+    const service = await api(config, "POST", `/sessions/${session.id}/services`, {
+        port,
+        name,
+        protocol,
+    });
+    say(`${green("✓")} Service ${service.label ?? ""} · ${service.status}`);
+    say(`  ${cobalt(serviceUrl(config, service))}`);
+    if (protocol === "udp") {
+        say(dim(`  udp — a reply is the only reachability signal; silence just relays`));
+    }
+    else if (service.status !== "reachable") {
+        say(dim(`  nothing answered on :${port} yet — the URL goes live when something listens`));
+    }
+};
+const serviceList = async (config) => {
+    const services = await api(config, "GET", "/services");
+    if (services.length === 0) {
+        say(dim("no live services — mend service add <port> adopts a listening one"));
+        return;
+    }
+    for (const service of services)
+        printService(config, service);
+};
+const serviceStop = async (config, args) => {
+    const needle = args.find((a) => !a.startsWith("--"));
+    if (needle === undefined)
+        return fail("usage: mend service stop <name-or-id-prefix>");
+    const services = await api(config, "GET", "/services");
+    const matches = services.filter((service) => service.label === needle || service.id.startsWith(needle));
+    if (matches.length === 0)
+        return fail(`no live service matches "${needle}"`);
+    const match = matches[0];
+    if (matches.length > 1 || match === undefined) {
+        return fail(`"${needle}" is ambiguous — use more of the id`);
+    }
+    const stoppedService = await api(config, "POST", `/services/${match.id}/stop`);
+    say(`${green("✓")} stopped · ${stoppedService.label ?? stoppedService.id.slice(0, 8)}`);
+};
+const findLiveService = async (config, needle) => {
+    const services = await api(config, "GET", "/services");
+    const matches = services.filter((service) => service.label === needle || service.id.startsWith(needle));
+    if (matches.length === 0)
+        return fail(`no live service matches "${needle}"`);
+    const match = matches[0];
+    if (matches.length > 1 || match === undefined) {
+        return fail(`"${needle}" is ambiguous — use more of the id`);
+    }
+    return match;
+};
+/**
+ * Start and supervise a Service: the command runs as its own PTY process in
+ * the session's workspace (own record = its logs), Mend waits for the
+ * declared port to answer, then exposes it like any Service. The command
+ * never occupies the agent's terminal or a tool call.
+ */
+const serviceRun = async (config, args) => {
+    const dashdash = args.indexOf("--");
+    const usage = "usage: mend service run [session] --port <port> [--name <n>] [--udp] -- <command...>\n" +
+        "       mend service run [session] <name>          (a declared recipe)";
+    // No explicit command = a DECLARED Service: resolve the name against the
+    // session worktree's mend.toml and start (or adopt) its recipe.
+    if (dashdash === -1) {
+        const positionals = args.filter((a) => !a.startsWith("--"));
+        const name = positionals.at(-1);
+        if (name === undefined)
+            return fail(usage);
+        const prefix = positionals.length > 1 ? positionals[0] : undefined;
+        const session = await resolveLiveSession(config, prefix);
+        const recipes = await api(config, "GET", `/sessions/${session.id}/recipes`);
+        const recipe = recipes.find((entry) => entry.name === name);
+        if (recipe === undefined) {
+            const known = recipes.map((entry) => entry.name).join(", ");
+            return fail(recipes.length === 0
+                ? `no mend.toml recipes in this worktree — declare [service.${name}] first`
+                : `no recipe named "${name}" — declared: ${known}`);
+        }
+        if (recipe.command === null) {
+            // A port-only recipe is an adopt: something else starts the listener.
+            const service = await api(config, "POST", `/sessions/${session.id}/services`, {
+                port: recipe.port,
+                name: recipe.name,
+                protocol: recipe.protocol,
+            });
+            say(`${green("✓")} Service ${service.label ?? ""} · ${service.status}`);
+            say(`  ${cobalt(serviceUrl(config, service))}`);
+            return;
+        }
+        const service = await withSpinner(recipe.protocol === "udp"
+            ? `starting ${recipe.name} (udp :${recipe.port})…`
+            : `starting ${recipe.name} — waiting for :${recipe.port} to answer…`, api(config, "POST", `/sessions/${session.id}/services/run`, {
+            argv: ["sh", "-c", recipe.command],
+            port: recipe.port,
+            name: recipe.name,
+            protocol: recipe.protocol,
+        }));
+        say(`${green("✓")} Service ${service.label ?? ""} · ${service.status}`);
+        say(`  ${cobalt(serviceUrl(config, service))}`);
+        say(dim(`  logs: mend service logs ${service.label ?? service.id.slice(0, 8)}`));
+        return;
+    }
+    const argv = args.slice(dashdash + 1);
+    if (argv.length === 0)
+        return fail(usage);
+    const head = args.slice(0, dashdash);
+    const portFlag = head.indexOf("--port");
+    const port = portFlag !== -1 ? Number(head[portFlag + 1]) : Number.NaN;
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return fail(usage);
+    const nameFlag = head.indexOf("--name");
+    const name = nameFlag !== -1 && head[nameFlag + 1] !== undefined ? String(head[nameFlag + 1]) : null;
+    const protocol = head.includes("--udp") ? "udp" : "tcp";
+    const prefix = head.find((a, i) => !a.startsWith("--") && i !== portFlag + 1 && i !== nameFlag + 1);
+    const session = await resolveLiveSession(config, prefix);
+    const service = await withSpinner(protocol === "udp"
+        ? `starting ${name ?? argv[0]} (udp :${port})…`
+        : `starting ${name ?? argv[0]} — waiting for :${port} to answer…`, api(config, "POST", `/sessions/${session.id}/services/run`, {
+        argv,
+        port,
+        name,
+        protocol,
+    }));
+    say(`${green("✓")} Service ${service.label ?? ""} · ${service.status}`);
+    say(`  ${cobalt(serviceUrl(config, service))}`);
+    say(dim(`  logs: mend service logs ${service.label ?? service.id.slice(0, 8)}`));
+};
+/**
+ * Watch a supervised Service's output: record replay, then live tail. A DEAD
+ * Service still answers — its record outlives the process — printed once
+ * instead of followed.
+ */
+const serviceLogs = async (config, args) => {
+    const needle = args.find((a) => !a.startsWith("--"));
+    if (needle === undefined)
+        return fail("usage: mend service logs <name-or-id-prefix>");
+    const everything = await api(config, "GET", "/services?all=1");
+    const matches = everything.filter((service) => service.label === needle || service.id.startsWith(needle));
+    if (matches.length === 0)
+        return fail(`no service matches "${needle}"`);
+    // Prefer the live one; otherwise the newest ended one (list is newest-first).
+    const service = matches.find((m) => m.status !== "exited" && m.status !== "stopped") ?? matches[0];
+    if (service === undefined)
+        return fail(`no service matches "${needle}"`);
+    if (service.sealantSessionId === null) {
+        return fail(`"${needle}" is an adopted port — no process of Mend's, no logs. mend service run supervises.`);
+    }
+    if (service.status === "exited" || service.status === "stopped") {
+        // Post-mortem: print the record, don't attach.
+        const output = await api(config, "GET", `/processes/${service.id}/output`);
+        say(dim(`${service.label ?? service.id.slice(0, 8)} · ${service.status} — recorded output:`));
+        say("");
+        process.stdout.write(output.text.endsWith("\n") ? output.text : `${output.text}\n`);
+        process.exit(0);
+    }
+    say(dim(`following ${service.label ?? service.id.slice(0, 8)} — Ctrl+C detaches, the service keeps running`));
+    say("");
+    const outcome = await attachTty(config, service.sessionId, "service", 0n, service.id, {
+        readOnly: true,
+    });
+    if (outcome === "unavailable") {
+        return fail(`tty attach unavailable: could not connect to ${config.url}`);
+    }
+    say("");
+    say(dim("stream ended"));
+    process.exit(0);
+};
+const serviceRestart = async (config, args) => {
+    const needle = args.find((a) => !a.startsWith("--"));
+    if (needle === undefined)
+        return fail("usage: mend service restart <name-or-id-prefix>");
+    const service = await findLiveService(config, needle);
+    const restarted = await withSpinner(`restarting ${service.label ?? service.id.slice(0, 8)}…`, api(config, "POST", `/services/${service.id}/restart`));
+    say(`${green("✓")} restarted · ${restarted.status}`);
+    say(`  ${cobalt(serviceUrl(config, restarted))}`);
+};
+/**
+ * Scaffold mend.toml from the project's own manifests. Static suggestion,
+ * not detection: package.json scripts and compose port mappings become
+ * recipe proposals the user confirms and commits. Nothing runs.
+ */
+const serviceInit = async (args) => {
+    const root = gitTopLevel(process.cwd()) ?? process.cwd();
+    const target = path.join(root, "mend.toml");
+    if (fs.existsSync(target)) {
+        return fail(`${target} already exists — edit it directly (init never merges)`);
+    }
+    const rootFiles = fs.readdirSync(root);
+    const proposals = [];
+    const readRoot = (name) => fs.readFileSync(path.join(root, name), "utf8");
+    if (rootFiles.includes("package.json")) {
+        proposals.push(...proposeFromPackageJson(readRoot("package.json"), rootFiles));
+    }
+    // Monorepo sweep: every workspace package, named after its folder.
+    const globs = workspaceGlobs(rootFiles.includes("pnpm-workspace.yaml") ? readRoot("pnpm-workspace.yaml") : null, rootFiles.includes("package.json") ? readRoot("package.json") : null);
+    for (const glob of globs) {
+        const parent = glob.replace(/\/?\*+$/, "");
+        const dirs = glob.endsWith("*")
+            ? fs.existsSync(path.join(root, parent))
+                ? fs.readdirSync(path.join(root, parent)).map((dir) => path.join(parent, dir))
+                : []
+            : [glob];
+        for (const dir of dirs) {
+            const manifest = path.join(root, dir, "package.json");
+            if (!fs.existsSync(manifest))
+                continue;
+            for (const proposal of proposeFromWorkspacePackage(path.basename(dir), fs.readFileSync(manifest, "utf8"), rootFiles)) {
+                if (!proposals.some((existing) => existing.name === proposal.name)) {
+                    proposals.push(proposal);
+                }
+            }
+        }
+    }
+    // Every compose flavor in the root, aggregated; non-default files need -f.
+    for (const composeName of rootFiles.filter(isComposeFile).toSorted()) {
+        const isDefault = composeName === "compose.yaml" || composeName === "docker-compose.yml";
+        for (const proposal of proposeFromCompose(readRoot(composeName))) {
+            if (!proposals.some((existing) => existing.name === proposal.name)) {
+                proposals.push({
+                    ...proposal,
+                    command: isDefault
+                        ? proposal.command
+                        : proposal.command.replace("docker compose ", `docker compose -f ${composeName} `),
+                    source: `${composeName}: ${proposal.source}`,
+                });
+            }
+        }
+    }
+    if (proposals.length === 0) {
+        return fail("nothing to propose — no server-ish package.json script with a nameable port, no compose ports");
+    }
+    const toml = renderMendToml(proposals);
+    say(dim(`proposed ${target}:`));
+    say("");
+    process.stdout.write(toml);
+    say("");
+    if (!args.includes("--yes")) {
+        if (process.stdin.isTTY !== true) {
+            return fail("non-interactive — pass --yes to write the file");
+        }
+        const readline = await import("node:readline/promises");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question("write it? [y/N] ");
+        rl.close();
+        if (answer.trim().toLowerCase() !== "y") {
+            say(dim("nothing written"));
+            return;
+        }
+    }
+    fs.writeFileSync(target, toml);
+    say(`${green("✓")} wrote ${target} — commit it, then: mend service run ${proposals[0]?.name}`);
+};
+const serviceCommand = async (config, args) => {
+    const [verb, ...rest] = args;
+    switch (verb) {
+        case "run":
+            return serviceRun(config, rest);
+        case "add":
+            return serviceAdd(config, rest);
+        case "init":
+            return serviceInit(rest);
+        case "list":
+        case undefined:
+            return serviceList(config);
+        case "logs":
+            return serviceLogs(config, rest);
+        case "restart":
+            return serviceRestart(config, rest);
+        case "stop":
+            return serviceStop(config, rest);
+        default:
+            // Sugar: `mend service mysql` reads as `mend service run mysql` — a
+            // bare word that isn't a verb is a recipe name. A miss still explains
+            // itself (declared recipes are listed in the failure).
+            return serviceRun(config, [verb, ...rest]);
+    }
+};
+// ─── keys: the machine's Mend deploy key (docs/GIT-ACCESS.md) ───────────────
+/** Print the public key with the one instruction that makes it useful. */
+const printGitKey = (key) => {
+    if (key.publicKey === null)
+        return;
+    say(key.publicKey);
+    if (key.fingerprint !== null)
+        say(dim(`  ${key.fingerprint}`));
+    say(dim("  add this as a deploy key on your git host (GitHub/GitLab/Gitea: repo"));
+    say(dim("  settings → deploy keys; grant write access if sessions should push),"));
+    say(dim("  then adopt with: mend adopt <ssh-url> --auth mend-key"));
+};
+const keysShow = async (config) => {
+    const key = await api(config, "GET", "/keys/git");
+    if (!key.exists) {
+        say(`no Mend key yet ${dim("— mend keys init generates one (ed25519, stays on the server host)")}`);
+        return;
+    }
+    printGitKey(key);
+};
+const keysInit = async (config) => {
+    const key = await api(config, "POST", "/keys/git");
+    say(`${green("✓")} Mend key ready ${dim("(private half stays on the server host)")}`);
+    printGitKey(key);
+};
+/**
+ * The ssh-agent bridge, client half (docs/GIT-ACCESS.md decision 2): relay
+ * the LOCAL ssh-agent to the Mend server over one standing WebSocket, so
+ * bridge-mode git ops sign with a key that never leaves this machine — a
+ * hardware key blinks here, not on the server. Agent-protocol messages are
+ * relayed verbatim (length-prefixed frames, base64 over JSON); the only
+ * inspection is each message's type byte, to say what is being asked.
+ */
+const keysShare = async (config) => {
+    const agentSock = process.env["SSH_AUTH_SOCK"];
+    if (agentSock === undefined || agentSock === "") {
+        return fail("SSH_AUTH_SOCK is not set — start (or plug in) your ssh-agent first");
+    }
+    const url = new URL(`${config.url}/api/keys/bridge/ws`);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("host", os.hostname());
+    if (config.token !== null)
+        url.searchParams.set("token", config.token);
+    /**
+     * One complete agent exchange against the local agent: fresh connection,
+     * write the framed request verbatim, read one framed response. A hardware
+     * key blocks here until the touch — hence the generous timeout.
+     */
+    const askLocalAgent = (payload) => new Promise((resolve, reject) => {
+        const connection = net.connect(agentSock, () => {
+            connection.write(payload);
+        });
+        const timer = setTimeout(() => {
+            connection.destroy();
+            reject(new Error("the agent did not answer within 60s — touch missed?"));
+        }, 60_000);
+        let pending = Buffer.alloc(0);
+        connection.on("data", (chunk) => {
+            pending = Buffer.concat([pending, chunk]);
+            if (pending.length >= 4 && pending.length >= 4 + pending.readUInt32BE(0)) {
+                clearTimeout(timer);
+                connection.end();
+                resolve(pending.subarray(0, 4 + pending.readUInt32BE(0)));
+            }
+        });
+        connection.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+    // Strictly one request at a time, in arrival order — the agent protocol is
+    // request/response and a hardware key cannot answer two touches at once.
+    let chain = Promise.resolve();
+    const SSH_AGENTC_SIGN_REQUEST = 13;
+    const SSH_AGENTC_REQUEST_IDENTITIES = 11;
+    let attempt = 0;
+    for (;;) {
+        const ws = new WebSocket(url);
+        const closed = new Promise((resolve) => {
+            ws.addEventListener("close", () => resolve(), { once: true });
+        });
+        const opened = await new Promise((resolve) => {
+            ws.addEventListener("open", () => resolve(true), { once: true });
+            ws.addEventListener("error", () => resolve(false), { once: true });
+        });
+        if (opened) {
+            attempt = 0;
+            say(`${green("●")} sharing this machine's ssh-agent with ${config.url}`);
+            say(dim(`  agent: ${agentSock} · signature requests print here · Ctrl-C stops sharing`));
+            ws.addEventListener("message", (event) => {
+                const text = typeof event.data === "string"
+                    ? event.data
+                    : Buffer.from(event.data).toString("utf8");
+                let frame;
+                try {
+                    frame = JSON.parse(text);
+                }
+                catch {
+                    return;
+                }
+                if (frame.t !== "req" ||
+                    typeof frame.id !== "number" ||
+                    typeof frame.payload !== "string") {
+                    return;
+                }
+                const id = frame.id;
+                const payload = Buffer.from(frame.payload, "base64");
+                const type = payload[4];
+                const context = typeof frame.context === "string" ? frame.context : "mend";
+                chain = chain.then(async () => {
+                    const started = Date.now();
+                    if (type === SSH_AGENTC_SIGN_REQUEST) {
+                        say(`${amber("✎")} signature requested by mend ${dim(`(${context})`)}`);
+                        say(dim("  waiting — touch your key if it blinks (up to 60s)…"));
+                    }
+                    else if (type === SSH_AGENTC_REQUEST_IDENTITIES) {
+                        say(dim(`  identities requested (${context})`));
+                    }
+                    try {
+                        const response = await askLocalAgent(payload);
+                        if (ws.readyState !== WebSocket.OPEN)
+                            return null;
+                        ws.send(JSON.stringify({ t: "res", id, payload: response.toString("base64") }));
+                        if (type === SSH_AGENTC_SIGN_REQUEST) {
+                            say(`${green("✓")} signed ${dim(`(${((Date.now() - started) / 1000).toFixed(1)}s)`)}`);
+                        }
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        if (ws.readyState === WebSocket.OPEN) {
+                            ws.send(JSON.stringify({ t: "err", id, message }));
+                        }
+                        if (type === SSH_AGENTC_SIGN_REQUEST)
+                            say(`${amber("✗")} not signed — ${message}`);
+                    }
+                    return null;
+                });
+            });
+        }
+        await closed;
+        attempt += 1;
+        const delay = Math.min(30_000, 1000 * 2 ** Math.min(attempt - 1, 5));
+        say(dim(`not connected — retrying in ${Math.round(delay / 1000)}s (Ctrl-C stops)`));
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+};
+const keysCommand = async (config, args) => {
+    const [verb] = args;
+    switch (verb) {
+        case "init":
+            return keysInit(config);
+        case "share":
+            return keysShare(config);
+        case "show":
+        case undefined:
+            return keysShow(config);
+        default:
+            return fail(`unknown keys command "${verb}" — try: mend keys init | show | share`);
+    }
+};
+const formatDotfileBytes = (bytes) => bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+const dotfilesShow = async (config) => {
+    const dotfiles = await api(config, "GET", "/dotfiles");
+    if (dotfiles.repository === null) {
+        say(`repo      ${dim("none")}`);
+    }
+    else {
+        const branch = dotfiles.repository.ref ?? "default branch";
+        const bootstrap = dotfiles.repository.bootstrap ? "install.sh on" : "install.sh off";
+        say(`repo      ${dotfiles.repository.url} ${dim(`(${branch} · ${bootstrap})`)}`);
+    }
+    if (dotfiles.snapshot === null) {
+        say(`snapshot  ${dim("none — sync from this machine: mend dotfiles sync --all")}`);
+        return;
+    }
+    const snapshot = dotfiles.snapshot;
+    say(`snapshot  ${snapshot.files.length} file${snapshot.files.length === 1 ? "" : "s"} · from ${snapshot.source} · ${dim(snapshot.sha.slice(0, 7))}`);
+    for (const file of snapshot.files) {
+        say(`  ${file.path.padEnd(36)} ${dim(formatDotfileBytes(file.bytes))}`);
+    }
+};
+/**
+ * `mend dotfiles sync` — capture home files ON THIS MACHINE and stream them into the server's
+ * per-user dotfiles store. This is the whole point of the store: the server may be a VPS whose
+ * home directory belongs to a service account, so contents are read here, where they live.
+ */
+const dotfilesSync = async (config, args) => {
+    const all = args.includes("--all");
+    const requestedPaths = args.filter((arg) => !arg.startsWith("--"));
+    const home = os.homedir();
+    if (!all && requestedPaths.length === 0) {
+        const found = scanDotfileCandidates(home);
+        if (found.length === 0) {
+            say(dim("no known config files found under ~"));
+            return;
+        }
+        let group = "";
+        for (const entry of found) {
+            if (entry.group !== group) {
+                group = entry.group;
+                say(dim(group));
+            }
+            say(`  ${entry.path.padEnd(36)} ${dim(formatDotfileBytes(entry.bytes))}`);
+        }
+        say("");
+        say(`sync everything with ${cobalt("mend dotfiles sync --all")}, or pick: ${cobalt("mend dotfiles sync .zshrc .gitconfig")}`);
+        return;
+    }
+    const selected = all ? scanDotfileCandidates(home).map((entry) => entry.path) : requestedPaths;
+    if (selected.length === 0)
+        return fail("nothing to sync — no known config files found under ~");
+    const read = readSyncFiles(home, selected);
+    if ("error" in read)
+        return fail(read.error);
+    const result = await api(config, "POST", "/dotfiles/snapshot", {
+        files: read.files,
+        source: os.hostname(),
+        merge: false,
+    });
+    const snapshot = result.snapshot;
+    if (snapshot === null)
+        return fail("the server accepted the sync but reports no snapshot");
+    say(`${green("synced")} ${snapshot.files.length} file${snapshot.files.length === 1 ? "" : "s"} from ${os.hostname()} · ${dim(snapshot.sha.slice(0, 7))} ${dim("— applies from the next session launch")}`);
+};
+const dotfilesCommand = async (config, args) => {
+    const [verb, ...rest] = args;
+    switch (verb) {
+        case "sync":
+            return dotfilesSync(config, rest);
+        case "show":
+        case undefined:
+            return dotfilesShow(config);
+        default:
+            return fail(`unknown dotfiles command "${verb}" — try: mend dotfiles sync | show`);
+    }
+};
+// ─── completions: live sessions under TAB ───────────────────────────────────
+/**
+ * The data half of shell completion: one live session per line as
+ * `id<TAB>description`. Scripts adapt the shape (zsh wants `id:desc`, bash
+ * wants bare ids). Never fails — a dead server just completes nothing.
+ */
+const completeCommand = async (config, args) => {
+    if (args[0] !== "session")
+        return;
+    try {
+        const [sessions, projects] = await Promise.all([
+            request(config, "GET", "/sessions"),
+            request(config, "GET", "/projects"),
+        ]);
+        const nameById = new Map(projects.map((p) => [p.id, p.name]));
+        for (const session of sessions) {
+            const project = nameById.get(session.projectId) ?? "";
+            process.stdout.write(`${session.id}\t${session.harness} · ${project} · ${session.branch}\n`);
+        }
+    }
+    catch {
+        // Completion must never surface an error into the user's TAB press.
+    }
+};
+const ZSH_COMPLETIONS = `#compdef mend
+_mend() {
+  local -a commands
+  commands=(
+    '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'
+    'service:reachable ports — add, list, stop'
+    'keys:the machine Mend deploy key — init, show, share'
+    'continue:resume with the pending follow-up' 'resume:rejoin a settled session'
+    'rejoin:attach if live, otherwise resume'
+    'projects:adopted projects' 'sessions:sessions with review facts' 'status:active sessions'
+    'ui:the dashboard' 'help:help'
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+  case $words[2] in
+    shell|attach|continue|resume|rejoin)
+      local -a sessions
+      sessions=(\${(f)"$(command mend __complete session 2>/dev/null | tr '\\t' ':')"})
+      (( \${#sessions} )) && _describe 'session' sessions
+      ;;
+  esac
+}
+_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 continue resume rejoin projects sessions status ui help" -- "$cur") )
+    return
+  fi
+  case \${COMP_WORDS[1]} in
+    shell|attach|continue|resume|rejoin)
+      COMPREPLY=( $(compgen -W "$(command mend __complete session 2>/dev/null | cut -f1)" -- "$cur") )
+      ;;
+  esac
+}
+complete -F _mend mend
+`;
+/** Print the hook for the named shell; the user wires it into their rc file. */
+const completionsCommand = (args) => {
+    switch (args[0]) {
+        case "zsh":
+            process.stdout.write(ZSH_COMPLETIONS);
+            return;
+        case "bash":
+            process.stdout.write(BASH_COMPLETIONS);
+            return;
+        default:
+            return fail('usage: mend completions zsh|bash — e.g. mend completions zsh > "$fpath[1]/_mend"');
+    }
+};
 // ─── supervised run: platform workspace + PTY + record ──────────────────────
 const supervisedRun = async (config, session, argv) => {
     const launched = await withSpinner("provisioning workspace — a first launch builds the harness image (can take minutes)…", api(config, "POST", `/sessions/${session.id}/launch`, { argv }));
@@ -731,10 +1464,30 @@ const dashboard = async (config) => {
 const HELP = `mend — the agent workbench
 
   mend                                  the dashboard: every project and session, live
-  mend adopt [source] [--name <name>]   adopt a repository into the store (default: cwd)
+  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 keys init                        generate the machine's Mend deploy key (ed25519)
+  mend keys show                        print the public key — add it as a deploy key on your git host
+  mend dotfiles                         your dotfiles on the server: repo + synced home files
+  mend dotfiles sync [--all | paths…]   capture config files from THIS machine into your store
+  mend keys share                       relay THIS machine's ssh-agent to the server (bridge mode:
+                                        hardware keys sign here; Ctrl-C stops sharing)
   mend codex|claude|opencode            new session worktree + launch the harness in it
   mend run -- <command...>              same, with an arbitrary command
   mend attach <session-id-prefix>       reattach this terminal to a running session
+  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
+  mend service run [session] <name>     start a declared Service (mend.toml recipe)
+  mend service <name>                   shorthand for the above
+  mend service init [--yes]             scaffold mend.toml from package.json + compose ports
+  mend service add [session] <port> [--name <n>] [--udp]
+                                        adopt a listening workspace port — reachable on this machine
+  mend service list                     every live service and its observed state
+  mend service logs <name-or-id>        follow a supervised service's output (replay, then live)
+  mend service restart <name-or-id>     re-run its recorded command — same URL
+  mend service stop <name-or-id>        stop a service (closes its host port)
   mend continue [session-id]            resume a session with its pending review follow-up
   mend resume [session-id] [--with h]   rejoin a settled session (state restored; --with switches harness)
   mend rejoin [session-id] [--harness h] attach if live, otherwise resume; newest live wins
@@ -742,10 +1495,11 @@ const HELP = `mend — the agent workbench
   mend sessions [--all] [--project p] [--json]
                                         sessions with review facts; JSON is stable for integrations
   mend status                           active sessions (alias of mend sessions)
+  mend completions zsh|bash             print the TAB-completion hook (live session ids under TAB)
 
   server: MEND_URL (default http://localhost:3105) · auth: MEND_TOKEN
   detach key: Ctrl+] (set MEND_DETACH_KEY=none when an outer multiplexer owns detaching)
-  config file: ~/.mend/cli.json { "url": ..., "token": ... }
+  config file: ~/.config/mend/cli.json { "url": ..., "token": ... }
 `;
 const main = async () => {
     const [command, ...rest] = process.argv.slice(2);
@@ -760,6 +1514,18 @@ const main = async () => {
             return launch(config, command, rest);
         case "attach":
             return attach(config, rest);
+        case "shell":
+            return shellCommand(config, rest);
+        case "service":
+            return serviceCommand(config, rest);
+        case "keys":
+            return keysCommand(config, rest);
+        case "dotfiles":
+            return dotfilesCommand(config, rest);
+        case "completions":
+            return completionsCommand(rest);
+        case "__complete":
+            return completeCommand(config, rest);
         case "continue":
             return continueSession(config, rest);
         case "resume":

package/dist/service-init.js

@@ -0,0 +1,227 @@
+/**
+ * `mend service init` — the mend.toml scaffolder (docs/SESSION-SERVICES.md).
+ * Static suggestion, not detection: an offline read of manifests the project
+ * already ships (package.json scripts, compose files), producing a proposal
+ * the user confirms and commits. Nothing runs; nothing is observed.
+ *
+ * Pure functions here; the command in main.ts does the I/O.
+ */
+/** Scripts that mean "a server" in practice; dev first, the rest as extras. */
+const SERVER_SCRIPTS = ["dev", "start", "serve", "preview"];
+/** Tool defaults for when the script names no port. */
+const TOOL_PORTS = [
+    [/\bvite\b(?!.*build)/, 5173],
+    [/\bnext dev\b/, 3000],
+    [/\bnuxt\b/, 3000],
+    [/\bastro dev\b/, 4321],
+    [/\bremix\b/, 3000],
+];
+const portFromScript = (script) => {
+    const explicit = /(?:--port[= ]|(?<![\w-])-p[= ])(\d{2,5})/.exec(script) ?? /\bPORT=(\d{2,5})/.exec(script);
+    if (explicit?.[1] !== undefined) {
+        const port = Number(explicit[1]);
+        if (port >= 1 && port <= 65535)
+            return { port, guessed: false };
+    }
+    for (const [pattern, port] of TOOL_PORTS) {
+        if (pattern.test(script))
+            return { port, guessed: true };
+    }
+    return null;
+};
+const packageManagerOf = (lockfiles) => {
+    if (lockfiles.includes("pnpm-lock.yaml"))
+        return "pnpm";
+    if (lockfiles.includes("yarn.lock"))
+        return "yarn";
+    if (lockfiles.includes("bun.lockb") || lockfiles.includes("bun.lock"))
+        return "bun";
+    return "npm";
+};
+/** Proposals from package.json scripts. `files` = names present in the repo root. */
+export const proposeFromPackageJson = (packageJsonText, rootFiles) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(packageJsonText);
+    }
+    catch {
+        return [];
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return [];
+    const scripts = parsed.scripts;
+    if (typeof scripts !== "object" || scripts === null)
+        return [];
+    const pm = packageManagerOf(rootFiles);
+    const proposals = [];
+    for (const scriptName of SERVER_SCRIPTS) {
+        const script = scripts[scriptName];
+        if (typeof script !== "string")
+            continue;
+        const port = portFromScript(script);
+        if (port === null)
+            continue; // no port, no Service — the user can add one by hand
+        proposals.push({
+            name: scriptName === "dev" ? "web" : scriptName,
+            command: `${pm} run ${scriptName}`,
+            port: port.port,
+            protocol: "tcp",
+            guessed: port.guessed,
+            source: `package.json "${scriptName}": ${script}`,
+        });
+        break; // one entry from scripts — the first server-ish one wins
+    }
+    return proposals;
+};
+/**
+ * Proposals from a compose file: every service with a published port becomes
+ * `docker compose up <name>` at the HOST side of the first mapping — that is
+ * where the workspace's docker sidecar publishes it.
+ */
+export const proposeFromCompose = (composeText) => {
+    // Deliberately narrow YAML reading: top-level `services:`, two-space
+    // indented names, `ports:` entries as "- host:container". A full YAML
+    // parser is not worth a dependency for a suggestion.
+    const proposals = [];
+    const lines = composeText.split("\n");
+    let inServices = false;
+    let current = null;
+    let inPorts = false;
+    for (const line of lines) {
+        if (/^services:\s*$/.test(line)) {
+            inServices = true;
+            continue;
+        }
+        if (inServices && /^\S/.test(line)) {
+            inServices = false; // left the services block
+        }
+        if (!inServices)
+            continue;
+        const serviceHead = /^ {2}([A-Za-z0-9._-]+):\s*$/.exec(line);
+        if (serviceHead?.[1] !== undefined) {
+            current = serviceHead[1];
+            inPorts = false;
+            continue;
+        }
+        if (current === null)
+            continue;
+        if (/^\s+ports:\s*$/.test(line)) {
+            inPorts = true;
+            continue;
+        }
+        if (inPorts) {
+            const mapping = /^\s+-\s+["']?(\d{2,5}):/.exec(line) ??
+                /^\s+-\s+["']?\$\{[A-Z_a-z0-9]+:-(\d{2,5})\}:/.exec(line) ??
+                /^\s+-\s+["']?(\d{2,5})["']?\s*$/.exec(line);
+            if (mapping?.[1] !== undefined) {
+                const port = Number(mapping[1]);
+                const protocol = /\/udp["']?\s*$/.test(line) ? "udp" : "tcp";
+                if (port >= 1 && port <= 65535 && !proposals.some((p) => p.name === current)) {
+                    proposals.push({
+                        name: current,
+                        command: `docker compose up ${current}`,
+                        port,
+                        protocol,
+                        guessed: false,
+                        source: `compose service "${current}" publishes :${mapping[1]}${protocol === "udp" ? "/udp" : ""}`,
+                    });
+                }
+                inPorts = false; // first mapping wins
+                continue;
+            }
+            if (!/^\s+-/.test(line))
+                inPorts = false;
+        }
+    }
+    return proposals;
+};
+/** Any compose flavor counts: compose.yaml, docker-compose.yml, compose.dev.yaml… */
+export const isComposeFile = (name) => /^(docker-)?compose(\.[\w.-]+)?\.ya?ml$/.test(name);
+/** Workspace dir globs from pnpm-workspace.yaml / package.json "workspaces". Single-level only. */
+export const workspaceGlobs = (pnpmWorkspaceText, packageJsonText) => {
+    const globs = [];
+    if (pnpmWorkspaceText !== null) {
+        let inPackages = false;
+        for (const line of pnpmWorkspaceText.split("\n")) {
+            if (/^packages:\s*$/.test(line)) {
+                inPackages = true;
+                continue;
+            }
+            if (inPackages && /^\S/.test(line))
+                inPackages = false;
+            if (!inPackages)
+                continue;
+            const entry = /^\s+-\s+["']?([^"'#]+?)["']?\s*$/.exec(line);
+            if (entry?.[1] !== undefined && !entry[1].startsWith("!"))
+                globs.push(entry[1].trim());
+        }
+    }
+    if (packageJsonText !== null) {
+        try {
+            const parsed = JSON.parse(packageJsonText);
+            if (Array.isArray(parsed.workspaces)) {
+                globs.push(...parsed.workspaces.filter((g) => typeof g === "string"));
+            }
+        }
+        catch {
+            // no workspaces to read
+        }
+    }
+    return globs;
+};
+/** A workspace package's proposal: named after its folder, run through the package manager. */
+export const proposeFromWorkspacePackage = (dirName, packageJsonText, rootFiles) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(packageJsonText);
+    }
+    catch {
+        return [];
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return [];
+    const pkg = parsed;
+    const scripts = pkg.scripts;
+    if (typeof scripts !== "object" || scripts === null)
+        return [];
+    const pkgName = typeof pkg.name === "string" ? pkg.name : dirName;
+    const pm = packageManagerOf(rootFiles);
+    const runner = pm === "pnpm"
+        ? (script) => `pnpm --filter ${pkgName} ${script}`
+        : pm === "yarn"
+            ? (script) => `yarn workspace ${pkgName} ${script}`
+            : (script) => `${pm} run ${script} --workspace ${pkgName}`;
+    for (const scriptName of SERVER_SCRIPTS) {
+        const script = scripts[scriptName];
+        if (typeof script !== "string")
+            continue;
+        const port = portFromScript(script);
+        if (port === null)
+            continue;
+        return [
+            {
+                name: dirName,
+                command: runner(scriptName),
+                port: port.port,
+                protocol: "tcp",
+                guessed: port.guessed,
+                source: `${dirName}/package.json "${scriptName}": ${script}`,
+            },
+        ];
+    }
+    return [];
+};
+/** The proposal as the file the user will commit. */
+export const renderMendToml = (proposals) => {
+    const blocks = proposals.map((proposal) => {
+        const lines = [
+            `# ${proposal.source}`,
+            `[service.${proposal.name}]`,
+            `command = ${JSON.stringify(proposal.command)}`,
+            proposal.guessed ? `port = ${proposal.port} # guessed — verify` : `port = ${proposal.port}`,
+            ...(proposal.protocol === "udp" ? [`protocol = "udp"`] : []),
+        ];
+        return lines.join("\n");
+    });
+    return `${blocks.join("\n\n")}\n`;
+};

package/dist/shared.js

@@ -9,6 +9,8 @@ export const HARNESS_COMMANDS = {
     codex: ["codex"],
     claude: ["claude"],
     opencode: ["opencode"],
+    // Not a coding agent: a plain bash session in its own recorded worktree.
+    shell: ["bash"],
 };
 /** How each harness takes an instruction as its opening prompt. */
 export const CONTINUE_COMMANDS = {

package/package.json

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