@proagentstore/cli 0.4.28 → 0.4.30

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

@@ -454,21 +454,28 @@ export function parseCommand(command) {
             i++;
         if (i >= src.length)
             break;
-        const start = i;
+        const tokenStart = i;
         let out = "";
-        let quote = null;
         while (i < src.length) {
             const ch = src[i];
-            if (quote) {
-                if (ch === quote)
-                    quote = null;
-                else
-                    out += ch;
-                i++;
-                continue;
-            }
-            if (ch === '"' || ch === "'") {
-                quote = ch;
+            // A DOUBLE quote always opens a span — that is what `--flag "two words"` means and
+            // what anyone typing this expects.
+            //
+            // A SINGLE quote opens one only at a token boundary (token start, or right after `=`),
+            // because in ordinary English it is an apostrophe. This field is a preset text box, not
+            // a shell: a real shell would pair the two apostrophes in `don't guess and don't stop`
+            // and hand the engine `dont guess and dont` plus a stray `stop`, which is exactly the
+            // mangling seen here. `--agent='my agent'` and `'my agent'` still work.
+            const opens = ch === '"' || (ch === "'" && (i === tokenStart || src[i - 1] === "="));
+            if (opens) {
+                const close = src.indexOf(ch, i + 1);
+                if (close !== -1) {
+                    out += src.slice(i + 1, close);
+                    i = close + 1;
+                    continue;
+                }
+                // Unterminated — the character is literal, not the start of a span.
+                out += ch;
                 i++;
                 continue;
             }
@@ -477,21 +484,7 @@ export function parseCommand(command) {
             out += ch;
             i++;
         }
-        if (quote) {
-            // UNTERMINATED quote → it was a literal character, not a quote. `don't` is ordinary
-            // English in a user-edited preset; treating the apostrophe as an opening quote made
-            // `--append-system-prompt don't guess` reach the engine as three broken arguments.
-            i = start;
-            let raw = "";
-            while (i < src.length && !isSpace(src[i])) {
-                raw += src[i];
-                i++;
-            }
-            tokens.push(raw);
-        }
-        else {
-            tokens.push(out);
-        }
+        tokens.push(out);
     }
     return { bin: tokens[0] ?? "", args: tokens.slice(1) };
 }

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/runner.js

@@ -9,6 +9,7 @@ import { McpRuntime } from "./mcp-runtime.js";
 import { HumanHandoffError, RunnerInputError } from "./errors.js";
 import { RunnerStore } from "./store.js";
 import { CodingRuntime } from "./coding/runtime.js";
+import { WORKFLOW_DRIVEN_TASKS } from "./task-types.js";
 /** True for a plain object. */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -39,7 +40,6 @@ const APPROVAL_REQUIRED_TASKS = new Set(["browser.open"]);
  * workflow then polled a dead session for 15 minutes before failing a run it had already
  * completed.
  */
-const WORKFLOW_DRIVEN_TASKS = new Set(["job.apply_agent", "browser.task"]);
 const require = createRequire(import.meta.url);
 export class LocalRunner {
     config;

package/dist/browser-runner/server.js

@@ -357,6 +357,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/browser-runner/store.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { WORKFLOW_DRIVEN_TASKS } from "./task-types.js";
 function emptyStore() {
     return {
         sessions: [],
@@ -50,7 +51,7 @@ export class RunnerStore {
             // to "failed", which re-mirrors to the board, resurrects the Retry button, and
             // slips past the API single-flight guard → a second concurrent apply on the one
             // browser page. Mirrors the API carve-out in expireOrphanedRuntimeTasks.
-            if (task.type === "job.apply_agent")
+            if (WORKFLOW_DRIVEN_TASKS.has(task.type))
                 continue;
             if (task.status === "needs_human" || task.status === "running") {
                 task.status = "failed";

package/dist/browser-runner/task-types.js

@@ -0,0 +1,20 @@
+/**
+ * Task types steered by a remote durable Workflow rather than executed by the runner.
+ *
+ * ONE list, in its own module because THREE places need it and they drifted: task creation had
+ * `job.apply_agent || browser.task`, `resumeTakeover` had only `job.apply_agent` (so resolving a
+ * stuck browse handoff destroyed the session), and `RunnerStore.expireInFlightTasks` still
+ * hardcodes its own copy — which meant restarting `pags up` failed a live browse run locally while
+ * the cloud side preserved it, leaving the two views of one durable run disagreeing.
+ *
+ * `browser.handoff` is the synthetic task `browserHandoff` creates for a caller that has none (the
+ * engine sign-in relay mints its own id for a coding session with no runner task). It belongs here
+ * for the same reason: the console's Resume button is agent-agnostic, so without it pressing
+ * Resume would complete and END the takeover mid-sign-in — reintroducing the exact bug the browse
+ * case was fixed for.
+ */
+export const WORKFLOW_DRIVEN_TASKS = new Set([
+    "job.apply_agent",
+    "browser.task",
+    "browser.handoff",
+]);

package/dist/index.js

@@ -1,10 +1,4 @@
 #!/usr/bin/env node
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 
 // src/index.ts
 import { createRequire as createRequire3 } from "module";
@@ -371,7 +365,7 @@ jobs:
 });
 
 // src/commands/login.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
 import { createServer } from "http";
 import { homedir } from "os";
 import { join as join3 } from "path";
@@ -472,14 +466,16 @@ var loginCommand = new Command3("login").description("Sign in with Google or Git
   }
 });
 var logoutCommand = new Command3("logout").description("Sign out and remove stored session").action(() => {
+  if (!existsSync3(TOKEN_FILE)) {
+    writeLine("Already signed out.");
+    return;
+  }
   try {
-    if (existsSync3(TOKEN_FILE)) {
-      const { unlinkSync } = __require("fs");
-      unlinkSync(TOKEN_FILE);
-    }
+    unlinkSync(TOKEN_FILE);
     writeLine("Signed out.");
-  } catch {
-    writeLine("Already signed out.");
+  } catch (err) {
+    writeError(`Could not remove ${TOKEN_FILE}: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
   }
 });
 var whoamiCommand = new Command3("whoami").description("Show current signed-in user").action(() => {
@@ -798,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,
@@ -820,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");
@@ -834,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();
@@ -842,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();
@@ -858,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);
@@ -868,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`);
@@ -919,11 +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 reason = ev.code === 4401 || ev.code === 1008 ? " (token expired \u2014 run `pags login` then `pags up`)" : "";
+      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);
@@ -933,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
@@ -943,10 +1041,10 @@ function createRunnerCommand() {
   const command = new Command6("runner").description(
     "Manage the local ProAgentStore browser runtime for ProAgentStore agents"
   );
-  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", "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) => {
+  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));
@@ -982,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());
       });
@@ -1184,7 +1282,7 @@ function printStep(label, status) {
   const icon = status === "ok" ? chalk.green("\u2713") : status === "fail" ? chalk.red("\u2717") : chalk.yellow("\u2026");
   console.log(pad + icon + " " + label);
 }
-async function waitForKey(keys) {
+async function waitForKey(keys, onInterrupt) {
   return new Promise((resolve5) => {
     readline.emitKeypressEvents(process.stdin);
     if (process.stdin.isTTY) process.stdin.setRawMode(true);
@@ -1192,6 +1290,10 @@ async function waitForKey(keys) {
     const onKeypress = (str, key) => {
       if (key?.ctrl && key.name === "c") {
         cleanup();
+        if (onInterrupt) {
+          onInterrupt();
+          return;
+        }
         process.exit(0);
       }
       const val = (str || "").trim().toLowerCase();
@@ -1287,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 }
@@ -1366,7 +1469,7 @@ var upCommand = new Command7("up").description("Start the browser runner for all
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
   while (true) {
-    const key = await waitForKey(["r", "l", "q"]);
+    const key = await waitForKey(["r", "l", "q"], shutdown);
     if (key === "q") {
       shutdown();
       break;

package/package.json

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