@proagentstore/cli 0.4.124 → 0.4.126

package/dist/browser-runner/native/contract.js

@@ -0,0 +1,17 @@
+/**
+ * Native desktop / Maestro runtime (`local_native`, #1057) — the wire contract between the API
+ * Worker and the runner.
+ *
+ * This file is copied BYTE-FOR-BYTE between `packages/browser-runner/src/native/contract.ts` and
+ * `workers/api/src/lib/native/contract.ts` (the two packages cannot import each other), and
+ * `workers/api/src/lib/native/contract.test.ts` fails if they differ. It imports nothing.
+ *
+ * Slice 1 is the FOUNDATION only: a read-only preflight that reports what this machine could do,
+ * plus the run/event shapes the later slices will use. Nothing here drives a screen, a mouse, a
+ * keyboard or a Maestro flow yet.
+ */
+/** The runner route the API calls (over the relay) to probe a machine. Read-only. */
+export const NATIVE_PREFLIGHT_PATH = "/native/preflight";
+/** The capability a runner advertises once it can answer {@link NATIVE_PREFLIGHT_PATH}. */
+export const NATIVE_PREFLIGHT_CAPABILITY = "native.preflight";
+export const NATIVE_BACKENDS = ["desktop", "maestro"];

package/dist/browser-runner/native/preflight.js

@@ -0,0 +1,172 @@
+/**
+ * `/native/preflight` (#1057, slice 1): what this machine could do for the `local_native` runtime
+ * — desktop control permissions and Maestro devices — WITHOUT doing any of it.
+ *
+ * Rules this module keeps:
+ *   - READ-ONLY. It runs fixed probe commands and installs nothing. It never prompts for an OS
+ *     permission either: on macOS the two checks are the "preflight" APIs that only report state
+ *     (`CGPreflightScreenCaptureAccess`, `AXIsProcessTrusted`), not the "request" ones that open a
+ *     system dialog. (`screencapture` is NOT used as the probe: without Screen Recording it still
+ *     exits 0 and captures only the wallpaper, so its exit code proves nothing.)
+ *   - NEVER THROWS. A missing tool, a timeout or garbage output becomes a state (`unknown`, not
+ *     installed, no devices) and a stable error code with a sentence the owner can act on.
+ *   - Parsing is pure and exported, so it is tested on recorded outputs — no live device needed.
+ *
+ * `adb devices` starts the adb server if it is not already running; that is adb's own behaviour
+ * when asked to list devices, not something installed or configured here.
+ */
+import { execFile } from "node:child_process";
+import { arch as osArch, platform as osPlatform } from "node:os";
+/** Run one probe command; never rejects. */
+export const execProbe = (cmd, args, timeoutMs = 8000) => new Promise((resolve) => {
+    execFile(cmd, args, { timeout: timeoutMs, windowsHide: true, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
+        const e = err;
+        if (e?.code === "ENOENT")
+            return resolve({ found: false, code: null, stdout: "", stderr: "" });
+        resolve({
+            found: true,
+            code: e ? (typeof e.code === "number" ? e.code : 1) : 0,
+            stdout: String(stdout ?? ""),
+            stderr: String(stderr ?? ""),
+            ...(e?.killed ? { timedOut: true } : {}),
+        });
+    });
+});
+// ── Pure parsers ────────────────────────────────────────────────────────────
+/** `osascript -l JavaScript` printing `true`/`false` → a permission state. */
+export function parseBooleanProbe(r) {
+    if (!r.found || r.timedOut || r.code !== 0)
+        return "unknown";
+    const out = r.stdout.trim().toLowerCase();
+    return out === "true" ? "granted" : out === "false" ? "denied" : "unknown";
+}
+/** `maestro --version` → its version, or null when it printed nothing recognisable. */
+export function parseMaestroVersion(r) {
+    if (!r.found || r.code !== 0)
+        return null;
+    const m = r.stdout.match(/\d+\.\d+(?:\.\d+)?/);
+    if (m)
+        return m[0];
+    // No version number: keep a short first line verbatim, and refuse a long one rather than cut it.
+    const first = r.stdout.trim().split("\n")[0] ?? "";
+    return first && first.length <= 40 ? first : null;
+}
+/** `adb devices -l` → attached devices (any state; `device` is the usable one). */
+export function parseAdbDevices(stdout) {
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        const t = line.trim();
+        if (!t || t.startsWith("List of devices") || t.startsWith("*"))
+            continue;
+        const [id, state, ...rest] = t.split(/\s+/);
+        if (!id || !state)
+            continue;
+        const model = rest.find((p) => p.startsWith("model:"))?.slice("model:".length);
+        out.push({ id, kind: "android", name: model ? model.replace(/_/g, " ") : id, state });
+    }
+    return out;
+}
+/** `xcrun simctl list devices booted --json` → booted simulators. */
+export function parseSimctlBooted(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    const devices = parsed?.devices;
+    if (!devices || typeof devices !== "object")
+        return [];
+    const out = [];
+    for (const list of Object.values(devices)) {
+        if (!Array.isArray(list))
+            continue;
+        for (const d of list) {
+            if (typeof d?.udid !== "string" || d.state !== "Booted")
+                continue;
+            out.push({ id: d.udid, kind: "ios_simulator", name: typeof d.name === "string" ? d.name : d.udid, state: "Booted" });
+        }
+    }
+    return out;
+}
+/** Combine the parts into one result with its error codes. Pure. */
+export function summarizePreflight(input) {
+    const { screenRecording, accessibility } = input;
+    const states = [screenRecording, accessibility];
+    const permissionState = states.includes("unsupported")
+        ? "unsupported"
+        : states.includes("denied")
+            ? "denied"
+            : states.every((s) => s === "granted")
+                ? "granted"
+                : "unknown";
+    const errors = [];
+    const add = (code, message) => errors.push({ code, message });
+    if (permissionState === "unsupported")
+        add("NATIVE_UNSUPPORTED_OS", `Desktop control is not supported on ${input.os} yet (macOS and Windows only).`);
+    if (permissionState === "denied") {
+        const missing = [screenRecording === "denied" ? "Screen Recording" : null, accessibility === "denied" ? "Accessibility" : null].filter(Boolean).join(" and ");
+        add("NATIVE_PERMISSIONS_MISSING", `This machine has not granted ${missing}. Grant it to the app that runs \`pags up\` (e.g. Terminal) in System Settings → Privacy & Security, then restart \`pags up\`.`);
+    }
+    if (!input.maestroInstalled)
+        add("NATIVE_MAESTRO_NOT_INSTALLED", "Maestro is not installed on this machine. The runner never installs it; install it yourself (https://maestro.mobile.dev) if you want phone or emulator automation.");
+    const usable = input.devices.filter((d) => d.state === "device" || d.state === "Booted");
+    if (input.maestroInstalled && usable.length === 0) {
+        add("NATIVE_DEVICE_NOT_FOUND", input.devices.length ? `No usable device: ${input.devices.map((d) => `${d.name} (${d.state})`).join(", ")}. Authorise or boot one.` : "No Android device/emulator or booted iOS simulator is connected.");
+    }
+    return {
+        os: input.os,
+        osVersion: input.osVersion,
+        arch: input.arch,
+        desktop: { screenRecording, accessibility, permissionState },
+        maestro: { installed: input.maestroInstalled, version: input.maestroVersion, adbInstalled: input.adbInstalled, simctlAvailable: input.simctlAvailable, connectedDevices: input.devices },
+        errors,
+        checkedAt: input.checkedAt,
+    };
+}
+// ── The probe ───────────────────────────────────────────────────────────────
+// CGPreflightScreenCaptureAccess is not in JXA's bridge metadata, so it is bound explicitly —
+// without the bind the call is "not a function" and the state would read `unknown`.
+const JXA_SCREEN = 'ObjC.import("CoreGraphics"); ObjC.bindFunction("CGPreflightScreenCaptureAccess", ["bool", []]); $.CGPreflightScreenCaptureAccess()';
+const JXA_AX = 'ObjC.import("ApplicationServices"); $.AXIsProcessTrusted()';
+const PS_UIA = "Add-Type -AssemblyName UIAutomationClient; if ([System.Windows.Automation.AutomationElement]::RootElement) { 'true' } else { 'false' }";
+export async function runNativePreflight(deps = {}) {
+    const exec = deps.exec ?? execProbe;
+    const platform = deps.platform ?? osPlatform();
+    const safe = (p) => p.catch(() => ({ found: false, code: null, stdout: "", stderr: "" }));
+    let osVersion = null;
+    let screenRecording = "unsupported";
+    let accessibility = "unsupported";
+    if (platform === "darwin") {
+        const [ver, screen, ax] = await Promise.all([safe(exec("sw_vers", ["-productVersion"])), safe(exec("osascript", ["-l", "JavaScript", "-e", JXA_SCREEN])), safe(exec("osascript", ["-l", "JavaScript", "-e", JXA_AX]))]);
+        osVersion = ver.code === 0 ? ver.stdout.trim() || null : null;
+        screenRecording = parseBooleanProbe(screen);
+        accessibility = parseBooleanProbe(ax);
+    }
+    else if (platform === "win32") {
+        // Windows has no per-app permission for screen capture or UI Automation: one availability probe.
+        const uia = parseBooleanProbe(await safe(exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", PS_UIA], 15000)));
+        screenRecording = uia;
+        accessibility = uia;
+    }
+    const [maestro, adb, simctl] = await Promise.all([
+        safe(exec("maestro", ["--version"], 15000)),
+        safe(exec("adb", ["devices", "-l"])),
+        platform === "darwin" ? safe(exec("xcrun", ["simctl", "list", "devices", "booted", "--json"])) : Promise.resolve({ found: false, code: null, stdout: "", stderr: "" }),
+    ]);
+    const devices = [...(adb.found && adb.code === 0 ? parseAdbDevices(adb.stdout) : []), ...(simctl.found && simctl.code === 0 ? parseSimctlBooted(simctl.stdout) : [])];
+    return summarizePreflight({
+        os: platform,
+        osVersion,
+        arch: deps.arch ?? osArch(),
+        screenRecording,
+        accessibility,
+        maestroVersion: parseMaestroVersion(maestro),
+        maestroInstalled: maestro.found && maestro.code === 0,
+        adbInstalled: adb.found,
+        simctlAvailable: simctl.found && simctl.code === 0,
+        devices,
+        checkedAt: (deps.now ?? Date.now)(),
+    });
+}

package/dist/browser-runner/runner.js

@@ -39,6 +39,7 @@ const CAPABILITIES = [
     "human.approval",
     "human.takeover",
     "tmux.control",
+    "native.preflight",
 ];
 /** How many times a task may attempt an action before handing off to a human. */
 export const MAX_AUTONOMOUS_ATTEMPTS = 3;

package/dist/browser-runner/server.js

@@ -5,6 +5,7 @@ import { probeGitSshIdentity } from "./coding/repo.js";
 import { checkEngine } from "./coding/engine-check.js";
 import { listGithubOrgs, listGithubRepos, searchGithubRepos, getGithubRepoDetail, getGithubCredentialScope } from "./coding/github-browse.js";
 import { routeLocalApplyHandoff } from "./local-apply/handoff-routes.js";
+import { runNativePreflight } from "./native/preflight.js";
 import { routeLocalApplyReconciliation } from "./local-apply/reconciliation-routes.js";
 export function createRunnerServer(runner) {
     return createServer(async (req, res) => {
@@ -105,6 +106,11 @@ async function route(runner, req, res) {
     if ((req.method === "GET" || req.method === "POST") && path === "/capabilities") {
         return json(res, 200, runner.capabilities());
     }
+    // #1057 slice 1: a READ-ONLY probe of what native desktop / Maestro control could do on this
+    // machine. Runs fixed probe commands, installs nothing, prompts for nothing, never throws.
+    if ((req.method === "GET" || req.method === "POST") && path === "/native/preflight") {
+        return json(res, 200, await runNativePreflight());
+    }
     if (req.method === "GET" && path === "/sessions") {
         return json(res, 200, { sessions: runner.store.listSessions() });
     }

package/dist/index.js

@@ -11,7 +11,7 @@ import {
 
 // src/index.ts
 import { createRequire as createRequire3 } from "module";
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 
 // src/commands/check.ts
 import { existsSync, readFileSync } from "fs";
@@ -1548,6 +1548,7 @@ var isTakeable = (verdict) => verdict === "dead";
 function holderWhere(lock) {
   if (lock.launch === "tmux") return `tmux session ${lock.launchDetail || "?"}`;
   if (lock.launch === "service") return "a background service (launchd/systemd)";
+  if (lock.launch === "background") return `the background (\`pags up --background\`${lock.launchDetail ? `, log ${lock.launchDetail}` : ""})`;
   if (lock.launch === "headless") return "headless";
   return lock.launchDetail ? `terminal ${lock.launchDetail}` : "a terminal";
 }
@@ -1565,6 +1566,7 @@ function holderMessage(lock, verdict) {
   }
   lines.push("", "  What you can do:");
   if (lock.launch === "tmux" && lock.launchDetail) lines.push(`    tmux attach -t ${lock.launchDetail}   \u2014 go to the one that is running`);
+  if (lock.launch === "background") lines.push(`    pags down                        \u2014 stop it (it has no window to close)`);
   lines.push(
     `    pags status                      \u2014 what it is doing, and anything else running here`,
     lock.launch === "service" ? `    (this one is a service \u2014 stop its launchd/systemd unit rather than replacing it)` : `    pags up --replace                \u2014 stop that one gracefully, then take over`
@@ -1573,6 +1575,7 @@ function holderMessage(lock, verdict) {
 }
 function detectLaunch(env = process.env, isTty = Boolean(process.stdout.isTTY)) {
   if (env.PAGS_SERVICE === "1") return { launch: "service", detail: env.PAGS_SERVICE_NAME?.trim() || "" };
+  if (env.PAGS_BACKGROUND === "1") return { launch: "background", detail: env.PAGS_BACKGROUND_LOG?.trim() || "" };
   if (env.TMUX) return { launch: "tmux", detail: env.TMUX_PANE?.trim() || env.TMUX.split(",")[0]?.split("/").pop() || "" };
   if (!isTty) return { launch: "headless", detail: "" };
   return { launch: "tty", detail: env.TERM_SESSION_ID?.trim() || env.WINDOWID?.trim() || "" };
@@ -3094,9 +3097,148 @@ function createRunnerCommand() {
 // src/commands/runner.ts
 var runnerCommand = createRunnerCommand();
 
+// src/commands/status.ts
+import { readFileSync as readFileSync9, statSync as statSync2, watchFile } from "fs";
+import { Command as Command9 } from "commander";
+
+// src/background.ts
+import { spawn as nodeSpawn } from "child_process";
+import { closeSync as closeSync2, existsSync as existsSync8, mkdirSync as mkdirSync7, openSync as openSync2, readFileSync as readFileSync8, renameSync as renameSync3, statSync, writeFileSync as writeFileSync6 } from "fs";
+import { dirname as dirname4, join as join9 } from "path";
+var BACKGROUND_ENV = "PAGS_BACKGROUND";
+var BACKGROUND_LOG_ENV = "PAGS_BACKGROUND_LOG";
+var BACKGROUND_RESTART_ENV = "PAGS_BACKGROUND_RESTART";
+var LOG_ROTATE_BYTES = 5 * 1024 * 1024;
+var backgroundLogPath = (account, env = process.env) => join9(configDir(env), "logs", `runner-${accountKey(account)}.log`);
+var backgroundStatePath = (account, env = process.env) => join9(configDir(env), `background-${accountKey(account)}.json`);
+function writeBackgroundState(path, state) {
+  mkdirSync7(dirname4(path), { recursive: true });
+  writeFileSync6(path, `${JSON.stringify(state)}
+`, { mode: 384 });
+}
+function readBackgroundState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync8(path, "utf-8"));
+    return parsed?.v === 1 && Number.isInteger(parsed.pid) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function rotateLog(path, maxBytes = LOG_ROTATE_BYTES) {
+  try {
+    if (statSync(path).size <= maxBytes) return false;
+  } catch {
+    return false;
+  }
+  renameSync3(path, `${path}.1`);
+  return true;
+}
+function shellQuote(arg, platform = process.platform) {
+  if (platform === "win32") return `"${arg.replace(/"/g, '""')}"`;
+  return /^[A-Za-z0-9_./:=@%+-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+function backgroundRestartCommand(execPath, script, upArgs, platform = process.platform) {
+  const argv = [execPath, script, ...upArgs, "--background"].map((a) => shellQuote(a, platform)).join(" ");
+  return platform === "win32" ? `set ${BACKGROUND_RESTART_ENV}=1&& ${argv}` : `${BACKGROUND_RESTART_ENV}=1 ${argv}`;
+}
+function spawnDetached(command, args, env, logPath, spawn5 = nodeSpawn) {
+  mkdirSync7(dirname4(logPath), { recursive: true });
+  rotateLog(logPath);
+  const fd = openSync2(logPath, "a", 384);
+  try {
+    const child = spawn5(command, args, { detached: true, stdio: ["ignore", fd, fd], env, windowsHide: true });
+    child.unref();
+    if (!child.pid) throw new Error("the runner process did not start");
+    return child.pid;
+  } finally {
+    closeSync2(fd);
+  }
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function waitForBackgroundHolder(childPid, read, alive, opts = {}) {
+  const deadline = Date.now() + (opts.timeoutMs ?? 3e4);
+  while (Date.now() < deadline) {
+    if (!alive(childPid)) return "exited";
+    const held = await read();
+    if (held.lock?.pid === childPid && held.verdict === "live") return "live";
+    await sleep(opts.intervalMs ?? 500);
+  }
+  return alive(childPid) ? "timeout" : "exited";
+}
+async function waitUntilTakeable(read, opts = {}) {
+  const deadline = Date.now() + (opts.timeoutMs ?? 15e3);
+  for (; ; ) {
+    const held = await read();
+    if (!held.lock || isTakeable(held.verdict)) return true;
+    if (Date.now() >= deadline) return false;
+    await sleep(opts.intervalMs ?? 500);
+  }
+}
+function tailLines(path, n) {
+  if (!existsSync8(path)) return null;
+  const lines = readFileSync8(path, "utf-8").split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  return lines.slice(Math.max(0, lines.length - n));
+}
+
+// src/commands/status.ts
+function describeStatus(lock, verdict, bg, now = Date.now()) {
+  if (!lock || verdict === "dead") {
+    const lines2 = ["Not running \u2014 no runner of yours is connected from this machine."];
+    if (bg) lines2.push(`The last background runner (pid ${bg.pid}, started ${new Date(bg.startedAt).toLocaleString()}) has stopped. Its log: ${bg.logPath} (\`pags logs\`).`);
+    lines2.push("", "Start one with `pags up` (this terminal) or `pags up --background` (no terminal).");
+    return { running: false, lines: lines2 };
+  }
+  const mins = Math.max(0, Math.round((now - lock.startedAt) / 6e4));
+  const state = verdict === "live" ? "Running" : verdict === "unresponsive" ? "Running, but NOT answering its health check (asleep, stopped or overloaded)" : "Probably running (its lock could not be fully read)";
+  const lines = [
+    `${state} \u2014 pid ${lock.pid}, up ${mins < 120 ? `${mins} min` : `${Math.round(mins / 60)} h`}, CLI ${lock.version || "?"}, machine ${lock.node}.`,
+    `Launched from ${holderWhere(lock)}.`
+  ];
+  if (lock.launch === "background" && bg && bg.pid === lock.pid) {
+    lines.push(`Started with ${bg.instances.length} agent${bg.instances.length === 1 ? "" : "s"}${bg.watching ? " (newly eligible ones attach as they appear)" : " (scoped: only these)"}:`);
+    for (const i of bg.instances) lines.push(`  ${i.name} (${i.id.slice(0, 8)})`);
+    lines.push("", `Logs: \`pags logs\` (${bg.logPath}). Stop: \`pags down\`.`);
+  } else if (lock.launch === "background") {
+    lines.push("", "Logs: `pags logs`. Stop: `pags down`.");
+  }
+  return { running: true, lines };
+}
+var statusCommand = new Command9("status").description("Is a runner running on this machine for your account \u2014 and how was it started").action(async () => {
+  const session = requireSession();
+  const held = await inspectHolder(lockPath(session.user.login));
+  const { running, lines } = describeStatus(held.lock, held.lock ? held.verdict : null, readBackgroundState(backgroundStatePath(session.user.login)));
+  writeLine("");
+  for (const line of lines) writeLine(`  ${line}`);
+  writeLine("");
+  if (!running) process.exitCode = 1;
+});
+var logsCommand = new Command9("logs").description("Show the background runner's log (`pags up --background`)").option("-n, --lines <n>", "How many recent lines to show", "50").option("-f, --follow", "Keep printing new lines as they are written").action((opts) => {
+  const session = requireSession();
+  const path = backgroundLogPath(session.user.login);
+  const n = Math.max(1, Number.parseInt(opts.lines, 10) || 50);
+  const lines = tailLines(path, n);
+  if (!lines) {
+    writeLine("");
+    writeLine("  No background runner log here yet \u2014 one is written by `pags up --background`.");
+    writeLine("  A foreground `pags up` shows its output in its own window (press `l`).");
+    writeLine("");
+    return;
+  }
+  for (const line of lines) writeLine(line);
+  if (!opts.follow) return;
+  let offset = statSync2(path).size;
+  watchFile(path, { interval: 1e3 }, (cur) => {
+    if (cur.size < offset) offset = 0;
+    if (cur.size === offset) return;
+    process.stdout.write(readFileSync9(path).subarray(offset, cur.size));
+    offset = cur.size;
+  });
+});
+
 // src/commands/up.ts
 import { createRequire as createRequire2 } from "module";
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 import { hostname as hostname7 } from "os";
 
 // src/tui.ts
@@ -3217,7 +3359,7 @@ async function waitForKey(keys, onInterrupt) {
 }
 
 // src/commands/up-restart.ts
-import { spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "child_process";
+import { spawn as nodeSpawn2, spawnSync as nodeSpawnSync } from "child_process";
 var UP_LAUNCHER_ENV = "PAGS_UP_LAUNCHER";
 function upRestartMode(env, platform, canExecve) {
   if (env[SERVICE_ENV] === "1") return "service";
@@ -3234,7 +3376,7 @@ function processRestartDeps() {
     execArgv: process.execArgv,
     script: process.argv[1],
     execve: typeof execve === "function" ? execve.bind(process) : void 0,
-    spawn: nodeSpawn,
+    spawn: nodeSpawn2,
     spawnSync: nodeSpawnSync,
     exit: (code) => process.exit(code),
     log: () => {
@@ -3323,7 +3465,7 @@ async function holderWork(lock, deps = {}) {
 }
 async function replaceHolder(lock, opts = {}, deps = {}) {
   const fetchImpl = deps.fetchImpl ?? fetch;
-  const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep2 = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const alive = deps.alive ?? pidAlive;
   const now = deps.now ?? Date.now;
   const work = await holderWork(lock, deps);
@@ -3348,7 +3490,7 @@ async function replaceHolder(lock, opts = {}, deps = {}) {
   const until = now() + REPLACE_EXIT_TIMEOUT_MS;
   while (now() < until) {
     if (!alive(lock.pid)) return { ok: true, lines: [`Replaced the \`pags up\` on pid ${lock.pid}`] };
-    await sleep(500);
+    await sleep2(500);
   }
   return {
     ok: false,
@@ -3359,10 +3501,67 @@ async function replaceHolder(lock, opts = {}, deps = {}) {
   };
 }
 
+// src/commands/up-background.ts
+import { spawn as nodeSpawn3 } from "child_process";
+var processDeps = () => ({
+  env: process.env,
+  execPath: process.execPath,
+  platform: process.platform,
+  spawn: nodeSpawn3,
+  alive: pidAlive,
+  inspect: inspectHolder,
+  log: (line) => writeLine(line),
+  step: printStep
+});
+async function startInBackground(start, deps = processDeps()) {
+  const account = start.session.user.login;
+  const logPath = backgroundLogPath(account, deps.env);
+  const upArgs = restartUpArgs(start.opts);
+  const env = {
+    ...deps.env,
+    PAGS_TOKEN: start.session.token,
+    PAGS_LOCK_ACCOUNT: account,
+    [BACKGROUND_ENV]: "1",
+    [BACKGROUND_LOG_ENV]: logPath,
+    [RESTART_COMMAND_ENV]: backgroundRestartCommand(deps.execPath, start.runnerArgs[0], upArgs, deps.platform)
+  };
+  delete env.PAGS_UP_SUPERVISED;
+  deps.step("Starting the runner in the background\u2026", "wait");
+  const pid = spawnDetached(deps.execPath, start.runnerArgs, env, logPath, deps.spawn);
+  writeBackgroundState(backgroundStatePath(account, deps.env), {
+    v: 1,
+    pid,
+    startedAt: Date.now(),
+    logPath,
+    args: [...upArgs, "--background"],
+    instances: start.instances,
+    watching: start.watching
+  });
+  const outcome = await waitForBackgroundHolder(pid, () => deps.inspect(start.lockFile), deps.alive, { timeoutMs: deps.timeoutMs });
+  if (outcome === "live") {
+    deps.step(`Running in the background (pid ${pid}) \u2014 this terminal can be closed`, "ok");
+    deps.log("");
+    deps.log(`  Serving ${start.instances.length} agent${start.instances.length === 1 ? "" : "s"}${start.watching ? ", and attaching newly eligible ones" : ""}.`);
+    deps.log("  It keeps running until `pags down`, a reboot, or logging out \u2014 it does not start by itself.");
+    deps.log("");
+    deps.log("    pags status   \u2014 is it running, and what is it serving");
+    deps.log(`    pags logs     \u2014 its output (${logPath})`);
+    deps.log("    pags down     \u2014 stop it");
+    deps.log("");
+    return 0;
+  }
+  deps.step(outcome === "exited" ? "The background runner stopped before it was ready" : "The background runner did not confirm it was ready", "fail");
+  for (const line of tailLines(logPath, 10) ?? []) deps.log(`    ${line}`);
+  deps.log("");
+  deps.log(outcome === "exited" ? "  Fix what the log says, then `pags up --background` again." : `  It may still be starting (pid ${pid}): check \`pags status\`, or stop it with \`pags down\`.`);
+  deps.log("");
+  return 1;
+}
+
 // src/commands/up.ts
 var API_BASE3 = "https://api.proagentstore.online";
 var CLI_VERSION2 = createRequire2(import.meta.url)("../package.json").version;
-var upCommand = new Command9("up").description("Start the browser runner for all your agent instances").option("--headless", "Run browser in headless mode").option("--instance <id>", "Connect to a specific instance only").option("--force", "Take over from another connected machine").option("--replace", "Stop the `pags up` already running here for this account, then take over").option("--now", "With --replace: stop it even though work is running on it (that work is lost)").action(async (opts) => {
+var upCommand = new Command10("up").description("Start the browser runner for all your agent instances").option("--headless", "Run browser in headless mode").option("--instance <id>", "Connect to a specific instance only").option("--force", "Take over from another connected machine").option("--replace", "Stop the `pags up` already running here for this account, then take over").option("--now", "With --replace: stop it even though work is running on it (that work is lost)").option("--background", "Run the runner in the background, with no terminal open (stop it with `pags down`)").action(async (opts) => {
   const session = requireSession();
   const state = {
     user: session.user.login,
@@ -3439,6 +3638,7 @@ var upCommand = new Command9("up").description("Start the browser runner for all
   state.activeInstance = instances.length === 1 ? instances[0].name || instances[0].slug || instances[0].id.slice(0, 8) : `${instances.length} agents`;
   printStep(`Connecting ${state.activeInstance}\u2026`, "wait");
   const lockFile = lockPath(session.user.login);
+  if (opts.background && process.env[BACKGROUND_RESTART_ENV] === "1") await waitUntilTakeable(() => inspectHolder(lockFile));
   const held = await inspectHolder(lockFile);
   if (held.lock && !isTakeable(held.verdict)) {
     if (!opts.replace) {
@@ -3464,6 +3664,10 @@ var upCommand = new Command9("up").description("Start the browser runner for all
   if (opts.headless) args.push("--headless");
   if (opts.force) args.push("--force");
   if (!opts.instance) args.push("--watch-instances");
+  if (opts.background) {
+    const code = await startInBackground({ session, opts, runnerArgs: args, instances: state.instances, lockFile, watching: !opts.instance });
+    process.exit(code);
+  }
   const child = spawn5(process.execPath, args, {
     stdio: ["ignore", "pipe", "pipe"],
     // The child is the lock HOLDER (#896): it owns the relay sockets, so it is what a
@@ -3600,7 +3804,7 @@ var upCommand = new Command9("up").description("Start the browser runner for all
     }
   }
 });
-var downCommand = new Command9("down").description("Stop the browser runner and disconnect").option("--now", "Stop it even though work is running on it (that work is lost)").action(async (opts) => {
+var downCommand = new Command10("down").description("Stop the browser runner and disconnect").option("--now", "Stop it even though work is running on it (that work is lost)").action(async (opts) => {
   clearScreen();
   printLogo(CLI_VERSION2);
   const session = requireSession();
@@ -3625,7 +3829,7 @@ var downCommand = new Command9("down").description("Stop the browser runner and
 // src/index.ts
 var require2 = createRequire3(import.meta.url);
 var { version } = require2("../package.json");
-var program = new Command10();
+var program = new Command11();
 program.name("pags").description(
   "ProAgentStore CLI \u2014 create and publish server-powered AI agents"
 ).version(version);
@@ -3634,6 +3838,8 @@ program.addCommand(logoutCommand);
 program.addCommand(whoamiCommand);
 program.addCommand(upCommand);
 program.addCommand(downCommand);
+program.addCommand(statusCommand);
+program.addCommand(logsCommand);
 program.addCommand(initCommand);
 program.addCommand(checkCommand);
 program.addCommand(publishCommand);

package/package.json

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