@proagentstore/cli 0.4.123 → 0.4.125

package/dist/browser-runner/local-apply/bridge.js

@@ -123,6 +123,7 @@ function withQuote(schema, required) {
 export class ApplyBridge {
     browser;
     host;
+    shots;
     /** Read by the runtime for the #975 diagnostic: 0 calls is the finding, not an internal detail. */
     actions = 0;
     pages = 0;
@@ -142,9 +143,47 @@ export class ApplyBridge {
     submitted = null;
     /** The last thing that stopped the work and was not resolved — the block reason if the run ends here. */
     blocked = null;
-    constructor(browser, host) {
+    constructor(browser, host, 
+    /** Replay frames (#1063), taken by the runner with every form control blurred — never a tool the CLI can call. */
+    shots) {
         this.browser = browser;
         this.host = host;
+        this.shots = shots;
+    }
+    /**
+     * The frame a successful call earns (#1063). A refused call earns none, so a model retrying a refused
+     * tool cannot fill the run's frame cap.
+     */
+    static shotPoint(name, submittedNow) {
+        if (submittedNow)
+            return "submit";
+        const points = {
+            browser_navigate: "navigated",
+            browser_navigate_back: "navigated",
+            browser_click: "clicked",
+            browser_snapshot: "snapshot",
+            browser_wait_for: "waited",
+            browser_type: "filled",
+            browser_select_option: "filled",
+            upload_artifact: "uploaded",
+            supervisor_checkpoint: "checkpoint",
+            ready_for_review: "review",
+            request_answer: "paused",
+            report_job_unavailable: "blocked",
+        };
+        return points[name] ?? null;
+    }
+    async callTool(name, args = {}) {
+        const submittedBefore = this.submitAttempted;
+        const res = await this.dispatch(name, args);
+        const point = res.isError ? null : ApplyBridge.shotPoint(name, this.submitAttempted && !submittedBefore);
+        if (point && this.shots) {
+            const seq = await this.shots.capture(this.browser, point);
+            // Metadata only: which frame, and why. The pixels — every form control blurred — stay in the runner.
+            if (seq)
+                this.host.emit({ type: "screenshot.captured", detail: { shot: seq, point } });
+        }
+        return res;
     }
     get done() {
         return this.reviewReady || this.submitAttempted || this.unavailable !== null;
@@ -189,7 +228,7 @@ export class ApplyBridge {
             },
         ];
     }
-    async callTool(name, args = {}) {
+    async dispatch(name, args) {
         if (this.done)
             return text("The application is finished for this run. Stop now.", true);
         if (name === "ready_for_review")

package/dist/browser-runner/local-apply/contract.js

@@ -29,6 +29,8 @@
 export const LOCAL_APPLY_TASK_TYPE = "local_browser.apply";
 export const LOCAL_APPLY_RUN_PATH = "/local-apply/run";
 export const LOCAL_APPLY_STATUS_PATH = "/local-apply/status";
+/** `POST {runId, afterSeq}` — a run's replay screenshots (#1063), the shape of `/local-browser/shots`. */
+export const LOCAL_APPLY_SHOTS_PATH = "/local-apply/shots";
 export const LOCAL_APPLY_RESUME_PATH = "/local-apply/resume";
 export const LOCAL_APPLY_CANCEL_PATH = "/local-apply/cancel";
 /** Read-only job-page check used before an email lead may enter material preparation. */
@@ -158,6 +160,7 @@ export const LOCAL_APPLY_EVENT_TYPES = [
     "supervisor.directive",
     "run.paused",
     "run.resumed",
+    "screenshot.captured",
     "note",
 ];
 export const LOCAL_APPLY_ENGINE_AUTHS = ["machine-login", "subscription", "api-key", "missing_login", "unknown"];
@@ -176,7 +179,7 @@ const isHttpUrl = (v) => /^https?:\/\/[^\s/]+/i.test(v);
 // from `LOCAL_APPLY_CONFIRMATION_MARKERS`, how many times the page was read, and whether it moved.
 // Each is an id, a count or a boolean — the same whitelist rule as everything else here, so no page
 // text and no typed value can ride along on a `submit.confirmed` / `submit.unconfirmed` event.
-const DETAIL_KEYS = new Set(["engine", "authMode", "engineAuth", "mode", "class", "tool", "decision", "reason", "rule", "role", "kind", "path", "sha256", "bytes", "gateId", "exitCode", "count", "status", "basis", "source", "checkpointId", "directive", "phase", "actions", "filled", "uploaded", "marker", "looks", "urlChanged", "titleChanged"]);
+const DETAIL_KEYS = new Set(["engine", "authMode", "engineAuth", "mode", "class", "tool", "decision", "reason", "rule", "role", "kind", "path", "sha256", "bytes", "gateId", "exitCode", "count", "status", "basis", "source", "checkpointId", "directive", "phase", "actions", "filled", "uploaded", "marker", "looks", "urlChanged", "titleChanged", "shot", "point"]);
 /** A validated event, or null. Detail keeps only whitelisted, primitive, bounded values. */
 export function parseLocalApplyEvent(raw) {
     if (!raw || typeof raw !== "object")

package/dist/browser-runner/local-apply/runtime.js

@@ -34,6 +34,7 @@ import { redactText, secretEnvValues } from "../local-browser/contract.js";
 import { finalText, missingLogin, signInHelp } from "../local-browser/engine.js";
 import { resolveWorkspacePath } from "../local-browser/runtime.js";
 import { ApplyBridge } from "./bridge.js";
+import { APPLY_SHOT_CAP, ShotRecorder } from "../local-browser/replay.js";
 import { confirmationSignals } from "./confirmation.js";
 import { listingUnavailableReason } from "./unavailable.js";
 import { LOCAL_APPLY_AUTH_MODES, LOCAL_APPLY_CAPS, LOCAL_APPLY_ENGINES, LOCAL_APPLY_MODES, LOCAL_APPLY_TASK_TYPE, parseLocalApplyResult, } from "./contract.js";
@@ -276,7 +277,8 @@ export class LocalApplyRuntime {
                         continue;
                     const checked = parsed.result;
                     this.runs.set(envelope.runId, {
-                        envelope, dir, token: "", state: "ended", events: raw.events, seq: raw.seq,
+                        // Replay frames are memory-only by design (#1063): a run reloaded after a restart has none.
+                        envelope, dir, token: "", state: "ended", events: raw.events, seq: raw.seq, shots: new ShotRecorder(0),
                         result: checked, allow: new Set(envelope.policy.allowDomains), grounding: [], secrets: [], activeSince: raw.endedAt,
                         activeMs: 0, waiters: [], output: [], engineAuth: checked.engineAuth, cancelled: false, timedOut: false,
                         checkpoints: new Map(), endedAt: raw.endedAt,
@@ -308,6 +310,7 @@ export class LocalApplyRuntime {
             token: randomBytes(24).toString("hex"),
             state: "running",
             events: [],
+            shots: new ShotRecorder(APPLY_SHOT_CAP, () => this.now()),
             seq: 0,
             allow: new Set(envelope.policy.allowDomains),
             grounding: [],
@@ -393,7 +396,7 @@ export class LocalApplyRuntime {
             limits: e.limits,
             mode: e.policy.mode,
             gateId: e.policy.submitGate?.gateId,
-        });
+        }, run.shots);
         if (spec.mcpConfig)
             writeFileSync(spec.mcpConfig.path, spec.mcpConfig.json, { mode: 0o600 });
         const child = this.spawn(spec.command, spec.args, { cwd: join(run.dir, "scratch"), env: spec.env, stdio: ["ignore", "pipe", "pipe"] });
@@ -638,6 +641,12 @@ export class LocalApplyRuntime {
         }
         return { runId, state: run.state };
     }
+    /** `POST /local-apply/shots {runId, afterSeq}` — the run's replay frames after `afterSeq` (#1063). */
+    shots(raw) {
+        const o = (raw && typeof raw === "object" ? raw : {});
+        const run = this.get(String(o.runId ?? ""));
+        return run.shots.page(run.envelope.runId, typeof o.afterSeq === "number" && o.afterSeq > 0 ? o.afterSeq : 0);
+    }
     status(raw) {
         const o = (raw && typeof raw === "object" ? raw : {});
         const run = this.get(String(o.runId ?? ""));

package/dist/browser-runner/local-browser/bridge.js

@@ -130,6 +130,7 @@ export function refRole(snapshot, ref) {
 export class BrowserBridge {
     browser;
     host;
+    shots;
     actions = 0;
     pages = 0;
     lastSnapshot = "";
@@ -141,9 +142,18 @@ export class BrowserBridge {
     summary = null;
     /** Tool calls that reached the bridge. Zero at exit means the CLI never used the browser (#944). */
     calls = 0;
-    constructor(browser, host) {
+    constructor(browser, host, 
+    /** Replay frames (#1063), taken by the runner at the points below — never a tool the CLI can call. */
+    shots) {
         this.browser = browser;
         this.host = host;
+        this.shots = shots;
+    }
+    /** Take a replay frame, best-effort; the trace only records that it exists (seq + capture point). */
+    async shot(point, url) {
+        const seq = await this.shots?.capture(this.browser, point, url ? { url } : {});
+        if (seq)
+            this.host.emit({ type: "screenshot.captured", ...this.currentHost(), detail: { shot: seq, point } });
     }
     /** What the CLI sees: the read-only browser tools that exist, plus the research tools. */
     async listTools() {
@@ -161,6 +171,7 @@ export class BrowserBridge {
             return this.reportFailure(args);
         if (name === "finish_research") {
             this.summary = typeof args.summary === "string" ? args.summary.slice(0, 4000) : "";
+            await this.shot("completed");
             return text("Recorded. The research is finished; stop now.");
         }
         if (WRITE_TOOLS.has(name))
@@ -179,11 +190,17 @@ export class BrowserBridge {
         if (name === "browser_snapshot") {
             this.lastSnapshot = textOf(res);
             this.host.emit({ type: "browser.snapshot", ...this.currentHost() });
+            if (!res.isError)
+                await this.shot("snapshot");
         }
+        if (name === "browser_wait_for" && !res.isError)
+            await this.shot("waited");
         if (name === "browser_navigate_back") {
             const state = await this.inspect();
-            if (state)
+            if (state) {
                 this.noteNavigation(state);
+                await this.shot("navigated", state.url);
+            }
         }
         return { content: [{ type: "text", text: textOf(res) }], ...(res.isError ? { isError: true } : {}) };
     }
@@ -244,7 +261,7 @@ export class BrowserBridge {
             await this.browser.callTool("browser_navigate_back", {}).catch(() => undefined);
             return this.refuse("browser_navigate", `${host} redirected to ${landedOn}, a site this run has not been allowed on. Open ${landedOn} with browser_navigate to ask the owner, or skip it.`);
         }
-        return this.landed(textOf(res), state);
+        return this.landed(textOf(res), state, "navigated");
     }
     async click(args) {
         const ref = typeof args.target === "string" ? args.target : typeof args.ref === "string" ? args.ref : "";
@@ -265,10 +282,10 @@ export class BrowserBridge {
             await this.browser.callTool("browser_navigate_back", {}).catch(() => undefined);
             return this.refuse("browser_click", `That link leads to ${host}, a site this run has not been allowed on. Open it with browser_navigate to ask the owner.`);
         }
-        return this.landed(textOf(res), state);
+        return this.landed(textOf(res), state, "clicked");
     }
     /** After a page change: count it, trace it, and stop for a person when the page needs one. */
-    async landed(toolText, known) {
+    async landed(toolText, known, point) {
         const state = known ?? (await this.inspect());
         if (!state)
             return text(toolText);
@@ -278,6 +295,7 @@ export class BrowserBridge {
         // Pauses, never obstacles (#947): a captcha, a sign-in, a bot check, an access-control page or a paywall is
         // for a PERSON in the browser on this machine — the run waits, and re-checks once resumed.
         const blocker = state.captcha ? "captcha" : state.login ? "login_required" : state.accessBlocked ? "access_blocked" : state.paywall ? "paywall" : null;
+        await this.shot(blocker || state.writeForm ? "blocked" : point, state.url);
         if (blocker) {
             const what = BLOCKER_WORDS[blocker];
             this.host.emit({ type: "browser.blocked", url: state.url, domain: host, detail: { reason: blocker } });

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

@@ -29,6 +29,8 @@ export const LOCAL_BROWSER_RUN_PATH = "/local-browser/run";
 export const LOCAL_BROWSER_CANCEL_PATH = "/local-browser/cancel";
 export const LOCAL_BROWSER_STATUS_PATH = "/local-browser/status";
 export const LOCAL_BROWSER_RESUME_PATH = "/local-browser/resume";
+/** `POST {runId, afterSeq}` — a run's replay screenshots (#1063), pulled like its status. */
+export const LOCAL_BROWSER_SHOTS_PATH = "/local-browser/shots";
 export const LOCAL_BROWSER_ENGINES = ["claude", "codex"];
 export const LOCAL_BROWSER_AUTH_MODES = ["subscription", "machine", "api-key"];
 export const LOCAL_BROWSER_MODES = ["research_only"];
@@ -45,6 +47,7 @@ export const LOCAL_BROWSER_EVENT_TYPES = [
     "finding.parsed",
     "run.paused",
     "run.resumed",
+    "screenshot.captured",
     "note",
 ];
 export const LOCAL_BROWSER_PLATFORM_EVENT_TYPES = ["run.requested", "runner.dispatched", "run.ended", "review.decision"];

package/dist/browser-runner/local-browser/replay.js

@@ -0,0 +1,74 @@
+import { evaluateResult } from "./bridge.js";
+/** Per-run caps (#1063): enough to replay a run, not enough to make storage unbounded. */
+export const SCOUT_SHOT_CAP = 60;
+export const APPLY_SHOT_CAP = 40;
+/** One frame, as base64 characters (~768 KiB of JPEG) — the API refuses larger, so the runner never sends one. */
+export const MAX_SHOT_BASE64 = Math.ceil((768 * 1024 * 4) / 3);
+/** One pull's reply stays well under the relay's message limit. At least one frame is always returned. */
+export const SHOTS_PAGE_BASE64 = 900 * 1024;
+const MASK_ID = "__pags_replay_mask";
+/** Runs in the page through the browser's own evaluate — never offered to the CLI. */
+export const MASK_FORM_CONTROLS = `() => {
+	let s = document.getElementById(${JSON.stringify(MASK_ID)});
+	if (!s) {
+		s = document.createElement("style");
+		s.id = ${JSON.stringify(MASK_ID)};
+		s.textContent = "input, textarea, select, option, [contenteditable], [contenteditable] * { filter: blur(8px) !important; }";
+		(document.head || document.documentElement).appendChild(s);
+	}
+	return document.getElementById(${JSON.stringify(MASK_ID)}) ? "masked" : "unmasked";
+}`;
+export const UNMASK_FORM_CONTROLS = `() => { const s = document.getElementById(${JSON.stringify(MASK_ID)}); if (s) s.remove(); return "unmasked"; }`;
+const textOf = (r) => (r.content ?? []).map((c) => c.text ?? "").join("\n");
+export class ShotRecorder {
+    cap;
+    now;
+    shots = [];
+    nextSeq = 0;
+    constructor(cap, now = Date.now) {
+        this.cap = cap;
+        this.now = now;
+    }
+    /**
+     * Take one frame, best-effort. Returns its seq, or null when none was kept: the cap is reached, the
+     * form controls could not be masked (fail closed), or the browser gave no image.
+     */
+    async capture(browser, point, meta = {}) {
+        if (this.nextSeq >= this.cap)
+            return null;
+        try {
+            const masked = await browser.callTool("browser_evaluate", { function: MASK_FORM_CONTROLS });
+            if (masked.isError || evaluateResult(textOf(masked)) !== "masked")
+                return null;
+            try {
+                const res = await browser.callTool("browser_take_screenshot", { type: "jpeg" });
+                const image = res.isError ? undefined : (res.content ?? []).find((c) => c.type === "image" && typeof c.data === "string" && c.data.length > 0);
+                if (!image?.data || image.data.length > MAX_SHOT_BASE64)
+                    return null;
+                const seq = ++this.nextSeq;
+                this.shots.push({ seq, point, ...(meta.url ? { url: meta.url } : {}), ...(meta.action ? { action: meta.action } : {}), mimeType: image.mimeType ?? "image/jpeg", data: image.data, at: new Date(this.now()).toISOString() });
+                return seq;
+            }
+            finally {
+                await browser.callTool("browser_evaluate", { function: UNMASK_FORM_CONTROLS }).catch(() => undefined);
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The frames after `afterSeq`, paged by size; `lastSeq` never runs past a frame not returned. */
+    page(runId, afterSeq) {
+        const out = [];
+        let size = 0;
+        for (const s of this.shots) {
+            if (s.seq <= afterSeq)
+                continue;
+            if (out.length && size + s.data.length > SHOTS_PAGE_BASE64)
+                break;
+            out.push(s);
+            size += s.data.length;
+        }
+        return { runId, shots: out, lastSeq: out.length ? out[out.length - 1].seq : afterSeq };
+    }
+}

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

@@ -25,6 +25,7 @@ import { join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { RunnerInputError } from "../errors.js";
 import { BrowserBridge, domainWithin } from "./bridge.js";
+import { SCOUT_SHOT_CAP, ShotRecorder } from "./replay.js";
 import { BRIDGE_ENV } from "./bridge-stdio.js";
 import { LOCAL_BROWSER_AUTH_MODES, LOCAL_BROWSER_ENGINES, LOCAL_BROWSER_TASK_TYPE, redactDetail, redactFinding, redactSourceFailure, redactText, secretEnvValues, } from "./contract.js";
 import { bridgeUnused, buildEngineSpec, finalText, missingLogin, observedEngineAuth, researchPrompt, signInHelp } from "./engine.js";
@@ -184,6 +185,7 @@ export class LocalBrowserRuntime {
             token: randomBytes(24).toString("hex"),
             state: "running",
             events: [],
+            shots: new ShotRecorder(SCOUT_SHOT_CAP, () => this.now()),
             seq: 0,
             consented: new Set(envelope.policy.consentedDomains),
             deny: new Set(envelope.policy.denyDomains),
@@ -228,7 +230,7 @@ export class LocalBrowserRuntime {
             allowListOnly: () => e.policy.allowDomains.length > 0,
             overTime: () => this.activeMs(run) >= e.limits.maxMinutes * 60_000,
             limits: e.limits,
-        });
+        }, run.shots);
         const bridgeScript = this.deps.bridgeScript ?? fileURLToPath(new URL("./bridge-stdio.js", import.meta.url));
         const spec = buildEngineSpec({
             engine: e.engine,
@@ -360,6 +362,12 @@ export class LocalBrowserRuntime {
             ...(run.result ? { result: run.result } : {}),
         };
     }
+    /** `POST /local-browser/shots {runId, afterSeq}` — the run's replay frames after `afterSeq` (#1063). */
+    shots(raw) {
+        const o = (raw && typeof raw === "object" ? raw : {});
+        const run = this.get(String(o.runId ?? ""));
+        return run.shots.page(run.envelope.runId, typeof o.afterSeq === "number" && o.afterSeq > 0 ? o.afterSeq : 0);
+    }
     /** Does this token belong to this run? The bridge forwarder's only credential. */
     authorizeBridge(runId, token) {
         const run = this.runs.get(runId);

package/dist/browser-runner/server.js

@@ -211,6 +211,9 @@ async function route(runner, req, res) {
     if (req.method === "POST" && path === "/local-browser/status") {
         return json(res, 200, runner.localBrowser.status(await readJson(req)));
     }
+    if (req.method === "POST" && path === "/local-browser/shots") {
+        return json(res, 200, runner.localBrowser.shots(await readJson(req)));
+    }
     if (req.method === "POST" && path === "/local-browser/resume") {
         return json(res, 200, runner.localBrowser.resume(await readJson(req)));
     }
@@ -237,6 +240,9 @@ async function route(runner, req, res) {
     if (req.method === "POST" && path === "/local-apply/status") {
         return json(res, 200, runner.localApply.status(await readJson(req)));
     }
+    if (req.method === "POST" && path === "/local-apply/shots") {
+        return json(res, 200, runner.localApply.shots(await readJson(req)));
+    }
     const handoff = await routeLocalApplyHandoff(runner.localApply, req.method, path, () => readJson(req));
     if (handoff)
         return json(res, 200, handoff);

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.123",
+  "version": "0.4.125",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",