@proagentstore/cli 0.4.29 → 0.4.31

package/dist/browser-runner/coding/headless.js

@@ -24,7 +24,16 @@ import { dirname, join } from "node:path";
 import { handlerFor } from "./handlers.js";
 export class HeadlessSession {
     config;
-    sessionName;
+    /**
+     * A human-readable label for this engine process (#247).
+     *
+     * Was `sessionName`, formatted `pags-<client>-<id>` — which looked exactly like a tmux
+     * target and was reported to the console as `tmuxSession`. The engine has not used tmux
+     * since it moved to the stream-json interface, so a user who did the obvious thing with a
+     * name like that (`tmux attach -t pags-claude-…`) got "session not found" and reasonably
+     * concluded their engine was broken. It addresses nothing — it is only ever displayed.
+     */
+    engineLabel;
     proc = null;
     buf = "";
     transcript = [];
@@ -55,7 +64,7 @@ export class HeadlessSession {
     spawnFailed = false;
     constructor(config) {
         this.config = config;
-        this.sessionName = `pags-${config.clientType}-${config.id}`;
+        this.engineLabel = `${config.clientType}:${config.id}`;
         this.claudeSessionId = readState(config.statePath, config.id);
         // Claude is the structured engine; everything else is a raw CLI.
         this.mode = config.clientType === "claude" ? "stream-json" : "raw";

package/dist/browser-runner/coding/repo.js

@@ -0,0 +1,63 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Repo/workdir helpers for the coding engine.
+ *
+ * These lived in `coding/tmux.ts` and have nothing to do with tmux — `ensureRepo` runs `git
+ * clone`. The coding engine stopped using tmux when it moved to the structured stream-json
+ * interface, so anyone cleaning up that module found its two most load-bearing functions
+ * inside it (#247). Split out so the tmux module is only tmux, and only the terminal-operator
+ * agents depend on it.
+ */
+/**
+ * A safe, collision-resistant label derived from an arbitrary string.
+ *
+ * Named for tmux because that is where it started, but the coding engine uses it purely as a
+ * display/identity label — no tmux target is derived from it (#247).
+ */
+export function sanitizeSessionName(label) {
+    return label.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "session";
+}
+/**
+ * Ensure a repo is present at `dir`, cloning it from `cloneUrl` if not. Idempotent
+ * — an existing checkout is left alone (no clobber). For private repos a GitHub
+ * App installation token is injected as `x-access-token` into an https URL. The
+ * coding CLI then runs in this directory.
+ *
+ * Returns the absolute working directory. Throws on clone failure so the caller
+ * can surface it (a session can't start without its repo).
+ */
+export function ensureRepo(dir, opts = {}) {
+    // A real checkout (has .git) is reused as-is.
+    if (existsSync(join(dir, ".git")))
+        return dir;
+    if (!opts.cloneUrl) {
+        // No source to clone from — just make the directory the engine will run in.
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    // The dir exists but has no `.git`. It could be a half-cloned/empty managed dir
+    // (safe to clear) OR a real user directory the caller passed as an explicit workDir
+    // (deleting it = data loss). NEVER recursively delete a non-empty non-git dir — refuse
+    // instead, so a mis-wired workDir+cloneUrl can't nuke a user's files. An empty dir is
+    // fine to remove (git clone needs an empty/absent target).
+    if (existsSync(dir)) {
+        const entries = readdirSync(dir);
+        if (entries.length > 0) {
+            throw new Error(`Refusing to clone into non-empty directory "${dir}" (no .git found) — move it aside or point at an empty path.`);
+        }
+        rmSync(dir, { recursive: true, force: true });
+    }
+    let url = opts.cloneUrl;
+    if (opts.token && /^https:\/\//.test(url)) {
+        url = url.replace(/^https:\/\//, `https://x-access-token:${opts.token}@`);
+    }
+    const args = ["clone", "--depth", "1"];
+    if (opts.branch)
+        args.push("--branch", opts.branch);
+    args.push(url, dir);
+    execFileSync("git", args, { stdio: "pipe", timeout: 180_000 });
+    return dir;
+}

package/dist/browser-runner/coding/runtime.js

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { defaultStatePath, HeadlessSession } from "./headless.js";
 import { InspectError, readGitRemoteOrigin, readRepoFile, repoTree, runRepoGit } from "./inspect.js";
-import { ensureRepo, sanitizeSessionName } from "./tmux.js";
+import { ensureRepo, sanitizeSessionName } from "./repo.js";
 /** Hard cap on a pane returned to the brain/console (matches the worker MAX_PANE_CHARS). */
 const MAX_PANE = 64 * 1024;
 export class CodingRuntime {
@@ -135,14 +135,14 @@ export class CodingRuntime {
         return [...this.sessions.entries()].map(([sessionId, s]) => ({
             sessionId,
             alive: s.alive,
-            tmuxSession: s.sessionName,
+            engineLabel: s.engineLabel,
         }));
     }
     /** Rich diagnostics for every tracked session — the console's transparency view. */
     diagnostics() {
         return [...this.sessions.entries()].map(([sessionId, s]) => ({
             sessionId,
-            tmuxSession: s.sessionName,
+            engineLabel: s.engineLabel,
             alive: s.alive,
             runState: s.alive ? s.runState() : "idle",
             ready: s.alive ? s.ready : false,

package/dist/browser-runner/coding/terminal.js

@@ -0,0 +1,256 @@
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { capturePane, createSession, killSession, listSessionsDetailed, runCommand as tmuxRunCommand, sendKey as tmuxSendKey, sendText as tmuxSendText, sessionExists } from "./tmux.js";
+function shellPath() {
+    return process.env.SHELL || "/bin/zsh";
+}
+function expandWorkDir(workDir) {
+    return resolve(String(workDir || "~").replace(/^~(?=$|\/)/, homedir()));
+}
+export function splitTerminalTarget(raw, fallback) {
+    const value = String(raw || "").trim();
+    const m = value.match(/^(tmux|kitty|iterm2):(.+)$/i);
+    if (m)
+        return { backend: m[1].toLowerCase(), id: m[2].trim() };
+    if (!fallback)
+        throw new Error("A target must include a backend prefix like `tmux:main`, or pass `backend` separately.");
+    return { backend: fallback, id: value };
+}
+export function listTerminalTargets(backend = "all") {
+    const out = [];
+    if (backend === "all" || backend === "tmux") {
+        for (const s of listSessionsDetailed()) {
+            out.push({
+                backend: "tmux",
+                id: s.name,
+                name: s.name,
+                attached: s.attached,
+                activeCommand: s.activeCommand,
+                activeWindow: s.activeWindow,
+                created: s.created,
+            });
+        }
+    }
+    if (backend === "all" || backend === "kitty")
+        out.push(...listKittyTargets());
+    if (backend === "all" || backend === "iterm2")
+        out.push(...listItermTargets());
+    return out;
+}
+export function captureTerminalTarget(target, opts = {}) {
+    const t = splitTerminalTarget(target, opts.backend);
+    switch (t.backend) {
+        case "tmux":
+            if (!sessionExists(t.id))
+                throw new Error(`No tmux session "${t.id}".`);
+            return capturePane(t.id, Math.min(Math.max(Number(opts.lines) || 200, 1), 2000));
+        case "kitty":
+            return kittyExec(["@", "get-text", "--match", `id:${t.id}`, "--extent", "all"], 5000);
+        case "iterm2":
+            return itermSessionScript(t.id, "return contents of theSession");
+    }
+}
+export function runTerminalCommand(target, command, backend) {
+    const t = splitTerminalTarget(target, backend);
+    if (!command.trim())
+        throw new Error("A `command` is required.");
+    switch (t.backend) {
+        case "tmux":
+            if (!sessionExists(t.id))
+                throw new Error(`No tmux session "${t.id}".`);
+            tmuxRunCommand(t.id, command);
+            return capturePane(t.id, 200);
+        case "kitty":
+            kittyExec(["@", "send-text", "--match", `id:${t.id}`, command]);
+            kittyExec(["@", "send-key", "--match", `id:${t.id}`, "enter"]);
+            return captureTerminalTarget(t.id, { backend: "kitty" });
+        case "iterm2":
+            itermSessionScript(t.id, `tell theSession to write text ${appleString(command)}`);
+            return captureTerminalTarget(t.id, { backend: "iterm2" });
+    }
+}
+export function sendTerminalKeys(target, opts) {
+    const t = splitTerminalTarget(target, opts.backend);
+    if (opts.text == null && (!opts.keys || opts.keys.length === 0))
+        throw new Error("Provide `text` and/or `keys` to send.");
+    switch (t.backend) {
+        case "tmux":
+            if (!sessionExists(t.id))
+                throw new Error(`No tmux session "${t.id}".`);
+            if (opts.text != null)
+                tmuxSendText(t.id, opts.text);
+            for (const key of opts.keys ?? [])
+                tmuxSendKey(t.id, key);
+            return capturePane(t.id, 200);
+        case "kitty":
+            if (opts.text != null)
+                kittyExec(["@", "send-text", "--match", `id:${t.id}`, opts.text]);
+            for (const key of opts.keys ?? [])
+                kittyExec(["@", "send-key", "--match", `id:${t.id}`, kittyKeyName(key)]);
+            return captureTerminalTarget(t.id, { backend: "kitty" });
+        case "iterm2":
+            if ((opts.keys ?? []).length > 0)
+                throw new Error("iTerm2 generic key events are not supported yet; send text or run a command.");
+            itermSessionScript(t.id, `tell theSession to write text ${appleString(opts.text ?? "")}`);
+            return captureTerminalTarget(t.id, { backend: "iterm2" });
+    }
+}
+export function createTerminalTarget(opts) {
+    const workDir = expandWorkDir(opts.workDir);
+    switch (opts.backend) {
+        case "tmux": {
+            const name = String(opts.name || "").trim();
+            if (!name)
+                throw new Error("A `name` is required for tmux.");
+            if (sessionExists(name))
+                return { backend: "tmux", id: name, name, existed: true, workDir };
+            createSession(name, workDir, opts.command);
+            return { backend: "tmux", id: name, name, workDir };
+        }
+        case "kitty": {
+            const args = ["@", "launch", "--type", "os-window", "--cwd", workDir];
+            if (opts.command)
+                args.push(shellPath(), "-lc", opts.command);
+            const id = kittyExec(args).trim();
+            return { backend: "kitty", id, name: opts.name || id, workDir };
+        }
+        case "iterm2": {
+            const script = [
+                'tell application "iTerm2"',
+                "create window with default profile",
+                "set theSession to current session of current window",
+                `tell theSession to write text ${appleString(`cd ${shellQuote(workDir)}${opts.command ? ` && ${opts.command}` : ""}`)}`,
+                "return ((index of current window) as text) & \":1:1\"",
+                "end tell",
+            ].join("\n");
+            const id = osascript(script).trim() || "1:1:1";
+            return { backend: "iterm2", id, name: opts.name || id, workDir };
+        }
+    }
+}
+export function killTerminalTarget(target, backend) {
+    const t = splitTerminalTarget(target, backend);
+    switch (t.backend) {
+        case "tmux":
+            return killSession(t.id);
+        case "kitty":
+            kittyExec(["@", "close-window", "--match", `id:${t.id}`]);
+            return true;
+        case "iterm2":
+            itermCloseTarget(t.id);
+            return true;
+    }
+}
+function listKittyTargets() {
+    try {
+        const raw = kittyExec(["@", "ls"], 5000);
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        const out = [];
+        for (const osWindow of parsed) {
+            const tabs = Array.isArray(osWindow.tabs) ? osWindow.tabs : [];
+            for (const tab of tabs) {
+                const windows = Array.isArray(tab.windows) ? tab.windows : [];
+                for (const win of windows) {
+                    const row = win;
+                    const id = String(row.id ?? "").trim();
+                    if (!id)
+                        continue;
+                    const title = String(row.title ?? row.user_vars ?? id);
+                    out.push({ backend: "kitty", id, name: title || id, activeWindow: String(tab.title ?? "") });
+                }
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function listItermTargets() {
+    try {
+        const script = [
+            'set out to ""',
+            'tell application "iTerm2"',
+            "repeat with wi from 1 to count of windows",
+            "repeat with ti from 1 to count of tabs of window wi",
+            "repeat with si from 1 to count of sessions of tab ti of window wi",
+            "set sid to (wi as text) & \":\" & (ti as text) & \":\" & (si as text)",
+            "set sname to name of session si of tab ti of window wi",
+            "set out to out & sid & (ASCII character 9) & sname & linefeed",
+            "end repeat",
+            "end repeat",
+            "end repeat",
+            "end tell",
+            "return out",
+        ].join("\n");
+        return osascript(script)
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .flatMap((line) => {
+            const [id, name] = line.split("\t");
+            return id ? [{ backend: "iterm2", id, name: name || id }] : [];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function kittyExec(args, timeoutMs = 5000) {
+    try {
+        return execFileSync("kitty", args, { encoding: "utf8", timeout: timeoutMs, stdio: "pipe" });
+    }
+    catch (e) {
+        throw new Error(`kitty remote control is unavailable. Start kitty with remote control enabled (for example, allow_remote_control yes). ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+function osascript(script) {
+    try {
+        return execFileSync("osascript", ["-e", script], { encoding: "utf8", timeout: 5000, stdio: "pipe" });
+    }
+    catch (e) {
+        throw new Error(`iTerm2 automation is unavailable. Open iTerm2 and grant macOS Automation/Accessibility permission if prompted. ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+function itermSessionScript(target, command) {
+    const [w, t, s] = target.split(":").map((v) => Math.max(1, Number.parseInt(v, 10) || 1));
+    const script = [
+        'tell application "iTerm2"',
+        `set theSession to session ${s} of tab ${t} of window ${w}`,
+        command,
+        "end tell",
+    ].join("\n");
+    return osascript(script);
+}
+function itermCloseTarget(target) {
+    const [w, t] = target.split(":").map((v) => Math.max(1, Number.parseInt(v, 10) || 1));
+    const script = [
+        'tell application "iTerm2"',
+        `close tab ${t} of window ${w}`,
+        "end tell",
+    ].join("\n");
+    return osascript(script);
+}
+function appleString(s) {
+    return JSON.stringify(s);
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function kittyKeyName(key) {
+    const k = key.trim();
+    if (/^enter$/i.test(k))
+        return "enter";
+    if (/^escape$/i.test(k))
+        return "escape";
+    if (/^tab$/i.test(k))
+        return "tab";
+    if (/^backspace$/i.test(k))
+        return "backspace";
+    if (/^c-/i.test(k))
+        return `ctrl+${k.slice(2).toLowerCase()}`;
+    return k.toLowerCase();
+}

package/dist/browser-runner/coding/tmux.js

@@ -1,6 +1,4 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
 /**
  * Low-level tmux primitives for the coding runtime.
  *
@@ -127,49 +125,3 @@ export function capturePane(target, lines = 200) {
     const captured = tmuxExec(["capture-pane", "-p", "-t", target, "-S", `-${lines}`, "-J"]);
     return stripAnsi(captured).trim();
 }
-/** A safe, collision-resistant tmux session name derived from an arbitrary label. */
-export function sanitizeSessionName(label) {
-    return label.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "session";
-}
-/**
- * Ensure a repo is present at `dir`, cloning it from `cloneUrl` if not. Idempotent
- * — an existing checkout is left alone (no clobber). For private repos a GitHub
- * App installation token is injected as `x-access-token` into an https URL. The
- * coding CLI then runs in this directory.
- *
- * Returns the absolute working directory. Throws on clone failure so the caller
- * can surface it (a session can't start without its repo).
- */
-export function ensureRepo(dir, opts = {}) {
-    // A real checkout (has .git) is reused as-is.
-    if (existsSync(join(dir, ".git")))
-        return dir;
-    if (!opts.cloneUrl) {
-        // No source to clone from — make the directory so tmux can cd into it.
-        if (!existsSync(dir))
-            mkdirSync(dir, { recursive: true });
-        return dir;
-    }
-    // The dir exists but has no `.git`. It could be a half-cloned/empty managed dir
-    // (safe to clear) OR a real user directory the caller passed as an explicit workDir
-    // (deleting it = data loss). NEVER recursively delete a non-empty non-git dir — refuse
-    // instead, so a mis-wired workDir+cloneUrl can't nuke a user's files. An empty dir is
-    // fine to remove (git clone needs an empty/absent target).
-    if (existsSync(dir)) {
-        const entries = readdirSync(dir);
-        if (entries.length > 0) {
-            throw new Error(`Refusing to clone into non-empty directory "${dir}" (no .git found) — move it aside or point at an empty path.`);
-        }
-        rmSync(dir, { recursive: true, force: true });
-    }
-    let url = opts.cloneUrl;
-    if (opts.token && /^https:\/\//.test(url)) {
-        url = url.replace(/^https:\/\//, `https://x-access-token:${opts.token}@`);
-    }
-    const args = ["clone", "--depth", "1"];
-    if (opts.branch)
-        args.push("--branch", opts.branch);
-    args.push(url, dir);
-    execFileSync("git", args, { stdio: "pipe", timeout: 180_000 });
-    return dir;
-}

package/dist/browser-runner/server.js

@@ -162,18 +162,12 @@ async function route(runner, req, res) {
         return json(res, 200, { sessions: runner.coding.list() });
     }
     if ((req.method === "GET" || req.method === "POST") && path === "/coding/diagnostics") {
-        const { listSessions: tmuxList } = await import("./coding/tmux.js");
-        const allTmux = tmuxList();
-        const pagsTmux = allTmux.filter((n) => n.startsWith("pags-"));
-        const tracked = runner.coding.diagnostics();
-        const trackedNames = new Set(tracked.map((s) => s.tmuxSession));
-        const orphanedTmux = pagsTmux.filter((n) => !trackedNames.has(n));
-        return json(res, 200, {
-            tracked,
-            orphanedTmux,
-            tmuxTotal: allTmux.length,
-            pagsTmuxTotal: pagsTmux.length,
-        });
+        // No tmux figures here any more (#247). The coding engine spawns a child process
+        // directly, so `pagsTmuxTotal` was structurally always 0 and `tmuxTotal` counted the
+        // user's own unrelated sessions — this is the panel someone opens BECAUSE something is
+        // wrong, and it pointed them at a false cause. The terminal-operator agents, which do
+        // use tmux, have their own /tmux/* endpoints and are unaffected.
+        return json(res, 200, { tracked: runner.coding.diagnostics() });
     }
     if (req.method === "POST" && path === "/coding/browse") {
         const { readdirSync, statSync } = await import("node:fs");
@@ -197,30 +191,14 @@ async function route(runner, req, res) {
             return json(res, 400, { error: e instanceof Error ? e.message : String(e), dir });
         }
     }
-    if (req.method === "POST" && path === "/coding/kill-tmux") {
-        const { killSession: tmuxKill, listSessions: tmuxList } = await import("./coding/tmux.js");
-        const b = await readJson(req);
-        let targets = [];
-        if (b.orphansOnly) {
-            const allTmux = tmuxList();
-            const pagsTmux = allTmux.filter((n) => n.startsWith("pags-"));
-            const tracked = new Set(runner.coding.diagnostics().map((s) => s.tmuxSession));
-            targets = pagsTmux.filter((n) => !tracked.has(n));
-        }
-        else if (b.sessions?.length) {
-            targets = b.sessions.filter((n) => typeof n === "string" && n.startsWith("pags-"));
-        }
-        else {
-            // Kill all pags-* tmux sessions
-            targets = tmuxList().filter((n) => n.startsWith("pags-"));
-            runner.coding.closeAll();
-        }
-        let killed = 0;
-        for (const name of targets) {
-            if (tmuxKill(name))
-                killed++;
-        }
-        return json(res, 200, { killed, sessions: targets });
+    // Close every tracked coding session. The path still says "kill-tmux" ON PURPOSE: an older
+    // runner must keep answering a newer API, and renaming it would 404 across that skew (#247).
+    // The tmux half is gone — it only ever targeted `pags-*` sessions, which the coding engine
+    // has never created. `closeAll()` is the part that always worked, and is now the whole job.
+    if (req.method === "POST" && (path === "/coding/kill-tmux" || path === "/coding/close-sessions")) {
+        const closed = runner.coding.diagnostics().map((s) => s.sessionId);
+        runner.coding.closeAll();
+        return json(res, 200, { closed: closed.length, sessions: closed });
     }
     // ── Read-only code inspection (the Co-pilot/Chat's "eyes" — no CLI driving) ──
     // Confined to the session's workDir by inspect.ts; errors surface as 400.
@@ -357,6 +335,60 @@ async function route(runner, req, res) {
         createSession(session, workDir, b.command ? String(b.command) : undefined);
         return json(res, 200, { session, created: true, workDir });
     }
+    // ── generic terminal connector ──────────────────────────────────────────
+    // One local-terminal vocabulary over backend-specific adapters. tmux is fully
+    // controllable; kitty needs remote control enabled; iTerm2 needs macOS Automation access.
+    if ((req.method === "GET" || req.method === "POST") && path === "/terminal/list") {
+        const { listTerminalTargets } = await import("./coding/terminal.js");
+        const b = req.method === "POST" ? await readJson(req) : { backend: "all" };
+        const backend = b.backend === "tmux" || b.backend === "kitty" || b.backend === "iterm2" ? b.backend : "all";
+        return json(res, 200, { targets: listTerminalTargets(backend) });
+    }
+    if (req.method === "POST" && path === "/terminal/capture") {
+        const { captureTerminalTarget } = await import("./coding/terminal.js");
+        const b = await readJson(req);
+        const target = String(b.target || "").trim();
+        if (!target)
+            return json(res, 400, { error: "A `target` is required." });
+        const backend = b.backend === "tmux" || b.backend === "kitty" || b.backend === "iterm2" ? b.backend : undefined;
+        return json(res, 200, { target, pane: captureTerminalTarget(target, { backend, lines: b.lines }) });
+    }
+    if (req.method === "POST" && path === "/terminal/run") {
+        const { runTerminalCommand } = await import("./coding/terminal.js");
+        const b = await readJson(req);
+        const target = String(b.target || "").trim();
+        const command = String(b.command ?? "");
+        if (!target)
+            return json(res, 400, { error: "A `target` is required." });
+        if (!command.trim())
+            return json(res, 400, { error: "A `command` is required." });
+        const backend = b.backend === "tmux" || b.backend === "kitty" || b.backend === "iterm2" ? b.backend : undefined;
+        return json(res, 200, { target, command, pane: runTerminalCommand(target, command, backend) });
+    }
+    if (req.method === "POST" && path === "/terminal/send") {
+        const { sendTerminalKeys } = await import("./coding/terminal.js");
+        const b = await readJson(req);
+        const target = String(b.target || "").trim();
+        if (!target)
+            return json(res, 400, { error: "A `target` is required." });
+        const backend = b.backend === "tmux" || b.backend === "kitty" || b.backend === "iterm2" ? b.backend : undefined;
+        return json(res, 200, { target, pane: sendTerminalKeys(target, { backend, text: b.text == null ? undefined : String(b.text), keys: b.keys ?? [] }) });
+    }
+    if (req.method === "POST" && path === "/terminal/session") {
+        const { createTerminalTarget, killTerminalTarget } = await import("./coding/terminal.js");
+        const b = await readJson(req);
+        const backend = b.backend === "tmux" || b.backend === "kitty" || b.backend === "iterm2" ? b.backend : undefined;
+        if (b.action === "kill") {
+            const target = String(b.target || "").trim();
+            if (!target)
+                return json(res, 400, { error: "A `target` is required." });
+            return json(res, 200, { target, killed: killTerminalTarget(target, backend) });
+        }
+        if (!backend)
+            return json(res, 400, { error: "`backend` must be tmux, kitty, or iterm2." });
+        const target = createTerminalTarget({ backend, name: b.name, workDir: b.workDir, command: b.command });
+        return json(res, 200, { target });
+    }
     return json(res, 404, { error: "Not found" });
 }
 function authorize(req, config) {

package/dist/index.js

@@ -794,14 +794,41 @@ async function waitForLocalRunner(opts, timeoutMs = 15e3) {
 
 // src/commands/runner/relay.ts
 import { hostname as hostname2 } from "os";
-async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force = false) {
+
+// src/commands/runner/membership.ts
+function isEligible(inst, thisNode) {
+  if (inst.status !== "active") return false;
+  if (inst.capabilities?.runtime == null) return false;
+  const pin = inst.config?.runnerNode;
+  if (pin && pin !== thisNode) return false;
+  return true;
+}
+function diffMembership(attached, eligible, thisNode, blocked = /* @__PURE__ */ new Set()) {
+  const have = new Set(attached);
+  const want = eligible.filter((i) => isEligible(i, thisNode));
+  const wantIds = new Set(want.map((i) => i.id));
+  return {
+    attach: want.filter((i) => !have.has(i.id) && !blocked.has(i.id)),
+    // Detach what is no longer eligible — unsubscribed, deactivated, or re-pinned to another
+    // machine. Leaving the socket open would keep the agent looking connected here while the
+    // platform routes its work elsewhere.
+    detach: [...have].filter((id) => !wantIds.has(id))
+  };
+}
+function instanceLabel(inst) {
+  const short = `${inst.id.slice(0, 8)}\u2026`;
+  return inst.name ? `${inst.name} (${short})` : short;
+}
+
+// src/commands/runner/relay.ts
+async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force = false, watchInstances = false) {
   const apiBase = pagsApiBase(opts.apiBase).replace(/^http/, "ws");
   const pagsToken = clean(opts.pagsToken) || clean(process.env.PAGS_TOKEN) || clean(loadSession()?.token);
   if (!pagsToken) throw new Error("PAGS token required for WebSocket relay");
   const runnerNode = hostname2();
   const capabilities = await requestRunner("GET", "/capabilities", { url: localUrl, token: runnerToken, instanceId: instanceIds[0] });
   const caps = Array.isArray(capabilities.capabilities) ? capabilities.capabilities.filter((item) => typeof item === "string") : [];
-  for (const id of instanceIds) {
+  const registerRuntime = async (id) => {
     try {
       await requestPags("POST", `/v1/instances/${apiPathSegment(id)}/runtime`, opts, {
         endpointUrl: localUrl,
@@ -816,11 +843,30 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
       const msg = e instanceof Error ? e.message : String(e);
       writeError(`register ${id.slice(0, 8)}\u2026 failed: ${msg}`);
     }
-  }
-  for (const id of instanceIds) {
+  };
+  for (const id of instanceIds) await registerRuntime(id);
+  const attached = /* @__PURE__ */ new Map();
+  const blocked = /* @__PURE__ */ new Set();
+  const attach = (id, label = `${id.slice(0, 8)}\u2026`) => {
+    if (attached.has(id)) return;
     const mintToken = () => requestPags("POST", `/v1/relay/${apiPathSegment(id)}/token`, { ...opts, pagsToken }, {}).then((r) => r.token);
-    openRelaySocket(id, apiBase, mintToken, localUrl, runnerToken, force);
-  }
+    attached.set(
+      id,
+      openRelaySocket(id, apiBase, mintToken, localUrl, runnerToken, force, (conflicted) => {
+        blocked.add(conflicted);
+        attached.delete(conflicted);
+      })
+    );
+    if (label) writeLine(`Attached agent: ${label}`);
+  };
+  const detach = (id, label = `${id.slice(0, 8)}\u2026`) => {
+    const handle = attached.get(id);
+    if (!handle) return;
+    handle.close();
+    attached.delete(id);
+    writeLine(`Detached agent: ${label}`);
+  };
+  for (const id of instanceIds) attach(id, "");
   writeLine("Runtime registered with PAGS \u2713");
   writeLine("");
   writeLine("\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
@@ -830,7 +876,7 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
   writeLine("\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
   const heartbeat = () => {
     const timer = setTimeout(async () => {
-      for (const id of instanceIds) {
+      for (const id of [...attached.keys()]) {
         await requestPags("POST", `/v1/instances/${apiPathSegment(id)}/runtime/heartbeat`, opts, { runnerNode }).catch(() => void 0);
       }
       heartbeat();
@@ -838,11 +884,44 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
     timer.unref();
   };
   heartbeat();
+  if (watchInstances) startDiscovery();
+  function startDiscovery() {
+    const tick = () => {
+      const timer = setTimeout(async () => {
+        try {
+          const res = await requestPags(
+            "GET",
+            "/v1/instances/my/instances",
+            { ...opts, pagsToken }
+          );
+          const { attach: toAttach, detach: toDetach } = diffMembership(
+            attached.keys(),
+            res.instances ?? [],
+            runnerNode,
+            blocked
+          );
+          for (const inst of toAttach) {
+            await registerRuntime(inst.id);
+            attach(inst.id, instanceLabel(inst));
+          }
+          for (const id of toDetach) detach(id);
+        } catch {
+        }
+        tick();
+      }, 2e4);
+      timer.unref();
+    };
+    tick();
+  }
 }
-function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, force = false) {
+function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, force = false, onConflict) {
   let backoffMs = 1e3;
   let reconnecting = false;
+  let closed = false;
+  let socket = null;
+  let retryTimer = null;
   const connect = async () => {
+    if (closed) return;
     let relayToken;
     try {
       relayToken = await mintToken();
@@ -854,7 +933,7 @@ function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, f
       }
       const hint = /401|token|sign/i.test(msg) ? " (run `pags login`)" : "";
       writeLine(`Relay token mint failed: ${instanceId.slice(0, 8)}\u2026${hint} \u2014 retrying in ${Math.round(backoffMs / 1e3)}s`);
-      setTimeout(() => {
+      retryTimer = setTimeout(() => {
         connect();
       }, backoffMs);
       backoffMs = Math.min(backoffMs * 2, 3e4);
@@ -864,6 +943,7 @@ function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, f
     if (force) params.set("force", "1");
     const url = `${wsBase}/v1/relay/${encodeURIComponent(instanceId)}/connect?${params.toString()}`;
     const ws = new WebSocket(url);
+    socket = ws;
     ws.onopen = () => {
       backoffMs = 1e3;
       writeLine(`Relay connected: ${instanceId.slice(0, 8)}\u2026`);
@@ -915,13 +995,19 @@ function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, f
       }
     };
     ws.onclose = (ev) => {
-      if (reconnecting) return;
+      if (closed || reconnecting) return;
+      if (ev.code === 4409 && !force) {
+        writeLine(`Relay conflict: ${instanceId.slice(0, 8)}\u2026 is connected on another machine \u2014 run \`pags up --force\` here to take it over.`);
+        closed = true;
+        onConflict?.(instanceId);
+        return;
+      }
       reconnecting = true;
       const said = (ev.reason || "").trim();
       const hint = ev.code === 4401 ? " \u2014 run `pags login`, then `pags up`" : ev.code === 4409 ? " \u2014 run `pags up --force` to take over" : "";
       const reason = said ? ` (${said}${hint})` : ev.code === 1008 ? " (token expired \u2014 run `pags login` then `pags up`)" : "";
       writeLine(`Relay disconnected: ${instanceId.slice(0, 8)}\u2026${reason} \u2014 reconnecting in ${Math.round(backoffMs / 1e3)}s`);
-      setTimeout(() => {
+      retryTimer = setTimeout(() => {
         reconnecting = false;
         connect();
       }, backoffMs);
@@ -931,6 +1017,20 @@ function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, f
     };
   };
   connect();
+  return {
+    close() {
+      closed = true;
+      if (retryTimer) {
+        clearTimeout(retryTimer);
+        retryTimer = null;
+      }
+      try {
+        socket?.close();
+      } catch {
+      }
+      socket = null;
+    }
+  };
 }
 
 // src/commands/runner/command.ts
@@ -944,7 +1044,7 @@ function createRunnerCommand() {
   command.command("start").description("Start the local ProAgentStore browser runtime in the foreground").option("--host <host>", "Host to bind", "127.0.0.1").option("--port <port>", "Port to bind (default: first free port from 49171)").option("--data-dir <path>", "Runner data directory").option("--token <token>", "Require this bearer token").option("--instance-id <id>", "Bind runner requests to a PAGS instance id").option("--headless", "Run Playwright headless").action(async (opts) => {
     await startRunnerForeground(opts);
   });
-  command.command("connect <instanceIds...>").description("Start ONE local runtime, connect via WebSocket relay, and register it for every given PAGS instance").option("--host <host>", "Host to bind", "127.0.0.1").option("--port <port>", "Port to bind", "49171").option("--data-dir <path>", "Runner data directory").option("--token <token>", "Runner bearer token. Defaults to PAGS_RUNNER_TOKEN or a generated token").option("--headless", "Run Playwright headless").option("--api-base <url>", "PAGS API base URL").option("--pags-token <token>", "PAGS session token. Defaults to PAGS_TOKEN").option("--runner-version <version>", "Runner version").option("--force", "Take over from another connected machine").action(async (instanceIds, opts) => {
+  command.command("connect <instanceIds...>").description("Start ONE local runtime, connect via WebSocket relay, and register it for every given PAGS instance").option("--host <host>", "Host to bind", "127.0.0.1").option("--port <port>", "Port to bind", "49171").option("--data-dir <path>", "Runner data directory").option("--token <token>", "Runner bearer token. Defaults to PAGS_RUNNER_TOKEN or a generated token").option("--headless", "Run Playwright headless").option("--api-base <url>", "PAGS API base URL").option("--pags-token <token>", "PAGS session token. Defaults to PAGS_TOKEN").option("--runner-version <version>", "Runner version").option("--force", "Take over from another connected machine").option("--watch-instances", "Attach newly eligible agents while running, without a restart").action(async (instanceIds, opts) => {
     const runnerToken = clean(opts.token) || clean(process.env.PAGS_RUNNER_TOKEN) || `pags_runner_${randomUUID()}`;
     const host = clean(opts.host) || "127.0.0.1";
     const port = clean(opts.port) || String(await findFreePort2(49171));
@@ -980,7 +1080,7 @@ function createRunnerCommand() {
     try {
       await waitForLocalRunner({ url: localUrl, token: runnerToken, instanceId: primary });
       writeLine(`Local browser runtime healthy at ${localUrl}`);
-      await connectViaRelay(instanceIds, localUrl, runnerToken, opts, Boolean(opts.force));
+      await connectViaRelay(instanceIds, localUrl, runnerToken, opts, Boolean(opts.force), Boolean(opts.watchInstances));
       await new Promise((resolvePromise) => {
         runner.on("exit", () => resolvePromise());
       });
@@ -1289,6 +1389,7 @@ var upCommand = new Command7("up").description("Start the browser runner for all
   const args = [cliPath, "runner", "connect", ...instances.map((i) => i.id)];
   if (opts.headless) args.push("--headless");
   if (opts.force) args.push("--force");
+  if (!opts.instance) args.push("--watch-instances");
   const child = spawn4(process.execPath, args, {
     stdio: ["ignore", "pipe", "pipe"],
     env: { ...process.env, PAGS_TOKEN: session.token }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proagentstore/cli",
-  "version": "0.4.29",
+  "version": "0.4.31",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",