@proagentstore/cli 0.4.33 → 0.4.35

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

@@ -40,7 +40,11 @@ export function gitArgv(cmd, opts = {}) {
     const clampN = Math.max(1, Math.min(200, Math.floor(opts.n ?? 20)));
     switch (cmd) {
         case "status":
-            return ["status", "--short"];
+            // `--branch` adds ONE header line (`## main...origin/main [ahead 1]`). Without it a
+            // caller can learn a tree is dirty but never which branch it is dirty on, which is how
+            // a delegated run pushed a PR branch and left the checkout parked there unnoticed
+            // (#276). Additive: every existing consumer keeps the same file lines it always got.
+            return ["status", "--short", "--branch"];
         case "diff":
             return opts.relPath ? ["diff", "--", opts.relPath] : ["diff"];
         case "diff-stat":

package/dist/browser-runner/index.js

@@ -2,6 +2,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { startRunnerServer } from "./server.js";
+import { reapOnStartup } from "./reaper.js";
 import { randomUUID } from "node:crypto";
 // Resilience: a stray error in any runtime must NOT take the whole runner down —
 // that drops the tunnel and forces the user to restart `pags up` (and lose their
@@ -71,6 +72,12 @@ if (!config.token && !LOOPBACK.has(config.host)) {
         `Set --token (or PAGS_RUNNER_TOKEN), or bind to 127.0.0.1.\n`);
     process.exit(1);
 }
+// Recover a machine that has already leaked (#274). A browser whose launcher was
+// SIGKILLed is reparented to init and runs forever — 41 of them took the owner's
+// machine to load 253. Nothing in-process can clean those up, so we do it here,
+// before we start competing for the same CPU. Narrow by construction: see the
+// SAFETY block in reaper.ts for why the user's real Chrome can never match.
+reapOnStartup((line) => process.stderr.write(`${line}\n`));
 const started = await startRunnerServer(config);
 process.stdout.write(`ProAgentStore browser runtime listening at ${started.url}\n`);
 process.stdout.write(`Data dir: ${config.dataDir}\n`);
@@ -79,12 +86,47 @@ if (config.token)
     process.stdout.write("Auth: bearer token required\n");
 if (config.instanceId)
     process.stdout.write(`Instance binding: ${config.instanceId}\n`);
+/**
+ * Exit once, and ALWAYS exit (#274).
+ *
+ * Three holes lived here, and each one ended with a user reaching for `kill -9`,
+ * which is precisely the signal that orphans the browser:
+ *
+ *  - `started.close()` rejects if the browser is already gone. `void shutdown()`
+ *    then produced an unhandled rejection, the handler above logged it, and the
+ *    process stayed up forever holding the port and the browser.
+ *  - A hung `browserContext.close()` (a wedged renderer) blocked exit with no
+ *    upper bound, looking identical to a freeze.
+ *  - Two signals, or a signal racing the parent-death watchdog, ran the teardown
+ *    twice concurrently.
+ *
+ * So: idempotent, failure-tolerant, and time-boxed. `process.exit` also runs
+ * Playwright's own synchronous exit handler, which kills any browser it launched
+ * in this process — that is what makes a clean exit leave nothing behind.
+ */
+let exiting = false;
 const shutdown = async () => {
-    await started.close();
+    if (exiting)
+        return;
+    exiting = true;
+    const forced = setTimeout(() => {
+        process.stderr.write("[runner] shutdown timed out after 10s; exiting anyway\n");
+        process.exit(0);
+    }, 10_000);
+    forced.unref();
+    try {
+        await started.close();
+    }
+    catch (err) {
+        process.stderr.write(`[runner] shutdown error (exiting anyway): ${err instanceof Error ? err.message : String(err)}\n`);
+    }
     process.exit(0);
 };
 process.on("SIGINT", () => void shutdown());
 process.on("SIGTERM", () => void shutdown());
+// SIGHUP was missing: closing the terminal that ran `pags up` killed the runner
+// without ever running teardown, leaving the browser behind.
+process.on("SIGHUP", () => void shutdown());
 // Self-exit if our parent (the `runner connect` CLI) dies — otherwise we'd orphan
 // and keep holding the port, making the NEXT `pags up` fail with EADDRINUSE / a 401
 // against our stale token. When the parent dies we're reparented (ppid changes to

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

@@ -1,6 +1,76 @@
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { createConnection } from "@playwright/mcp";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { sweepStalePlaywrightProfiles } from "./reaper.js";
+/**
+ * Throwaway profile dirs created by this module and not yet removed (#274).
+ *
+ * `stop()` cannot reliably win this race on its own: the MCP server releases the
+ * browser, but Chrome's exit is asynchronous and it rewrites `Local State` on the
+ * way out — measurably AFTER `stop()` has returned, so an rmSync there leaves a
+ * re-created directory behind. The browser is only certainly gone once Playwright's
+ * own `exit` handler has run, so the last pass belongs at process exit.
+ *
+ * This also covers the dir being stranded when `stop()` is never called at all —
+ * a throw between `start()` and `stop()`, which no `try/finally` in the caller
+ * would catch either.
+ */
+const ownedProfileDirs = new Set();
+let exitHookInstalled = false;
+/**
+ * Try to remove a profile dir now. It stays registered unless it is really gone,
+ * so a dir Chrome re-creates while shutting down gets another pass at exit rather
+ * than being forgotten after one failed attempt.
+ */
+function removeProfileDir(dir) {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // best effort; the dir is disk, not correctness
+    }
+    if (!existsSync(dir))
+        ownedProfileDirs.delete(dir);
+}
+/** Await a promise, giving up (never throwing) after `ms`. */
+async function withTimeout(p, ms) {
+    if (!p)
+        return;
+    let timer;
+    try {
+        await Promise.race([
+            p.catch(() => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function rememberProfileDir(dir) {
+    ownedProfileDirs.add(dir);
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    // Registered AFTER Playwright's own launch-time exit handler, so by the time
+    // this runs Playwright has already killed the browsers it started.
+    process.on("exit", () => {
+        for (const d of ownedProfileDirs) {
+            try {
+                rmSync(d, { recursive: true, force: true });
+            }
+            catch {
+                // exiting anyway
+            }
+        }
+    });
+}
 /**
  * Hosts the INDUSTRY-STANDARD `@playwright/mcp` server in the runner and an in-process
  * MCP client to drive it. Every browser action goes through the standard Playwright MCP
@@ -11,12 +81,51 @@ import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 export class McpRuntime {
     server;
     client;
+    /** A profile dir this instance created and is therefore responsible for deleting. */
+    ownedProfileDir;
     async start(opts) {
         if (this.client)
             return;
-        const browser = opts.cdpEndpoint
-            ? { cdpEndpoint: opts.cdpEndpoint }
-            : { userDataDir: opts.userDataDir, isolated: opts.isolated, launchOptions: { headless: opts.headless ?? false } };
+        let browser;
+        if (opts.cdpEndpoint) {
+            // Production: attach to the browser the runner already launched. Nothing
+            // is created here, so nothing can leak here.
+            browser = { cdpEndpoint: opts.cdpEndpoint };
+        }
+        else {
+            // This is the ONE path in this package that produced the `#274` orphans.
+            //
+            // `isolated: true` makes @playwright/mcp call the non-persistent
+            // `chromium.launch()`, and Playwright then mkdtemps
+            // `$TMPDIR/playwright_chromiumdev_profile-XXXXXX` and deletes it only on a
+            // clean close — so every SIGKILLed parent left both a running browser AND a
+            // few hundred MB of profile behind, under a name we did not know and could
+            // not clean up afterwards.
+            //
+            // Asking for a directory WE created gets the same isolation (it is fresh
+            // every start) while making the leak addressable: we know the path, we
+            // delete it in `stop()`, and it is named so a human can see where it came
+            // from. It also keeps the throwaway-profile pattern out of our own output,
+            // so the reaper's matches are unambiguously other people's abandonment.
+            // Self-heal before adding one more. Chrome writes its final state as it
+            // dies — after `stop()`, and after our own `exit` hook — so the last
+            // skeleton of a directory can outlive the process that owned it no matter
+            // when we try to delete it. Sweeping here means a stale one never survives
+            // a second run, without needing the runner to be restarted. Only touches
+            // dirs no live process holds; see reaper.ts for the safety argument.
+            try {
+                sweepStalePlaywrightProfiles();
+            }
+            catch {
+                // cleanup must never stop a browser from starting
+            }
+            const userDataDir = opts.userDataDir ?? mkdtempSync(join(tmpdir(), "pags-mcp-profile-"));
+            if (!opts.userDataDir) {
+                this.ownedProfileDir = userDataDir;
+                rememberProfileDir(userDataDir);
+            }
+            browser = { userDataDir, isolated: false, launchOptions: { headless: opts.headless ?? false } };
+        }
         // The runner is a trusted local process uploading the user's OWN résumé, which
         // lives under the runner's data dir (outside the CWD). Lift the file-root guard
         // (meant to stop an LLM reading arbitrary host files) so browser_file_upload can
@@ -40,9 +149,22 @@ export class McpRuntime {
         return (res.content || []).map((c) => c.text ?? "").join("\n");
     }
     async stop() {
-        await this.client?.close().catch(() => undefined);
-        await this.server?.close().catch(() => undefined);
+        // Bounded. Closing a persistent context flushes the whole profile to disk and
+        // on a cold/slow machine that measurably exceeds 10s — and a browser wedged
+        // mid-close would otherwise block teardown with no upper limit at all, which
+        // is the state that ends in someone sending the SIGKILL that orphans it (#274).
+        // Returning early is safe: the `exit` hook and reaper.ts's sweep both still run.
+        await withTimeout(this.client?.close(), 20_000);
+        await withTimeout(this.server?.close(), 20_000);
         this.client = undefined;
         this.server = undefined;
+        // Remove the profile only if we made it — a caller-supplied dir belongs to
+        // the caller. A best-effort pass now, ordered after the closes so the browser
+        // has released its locks; the `exit` hook above is the pass that always runs,
+        // and reaper.ts's startup sweep covers a process that was killed outright.
+        if (this.ownedProfileDir) {
+            removeProfileDir(this.ownedProfileDir);
+            this.ownedProfileDir = undefined;
+        }
     }
 }

package/dist/browser-runner/reaper.js

@@ -0,0 +1,281 @@
+import { execFileSync } from "node:child_process";
+import { readdirSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+const DEFAULT_MIN_AGE_MS = 10 * 60 * 1000;
+/**
+ * A throwaway browser-profile directory name, anchored.
+ *
+ * Two producers, both of which mkdtemp — so the trailing six characters are
+ * exactly what `fs.mkdtemp` appends, and pinning that length is what stops a
+ * user-chosen directory which merely CONTAINS this text from matching:
+ *
+ *  - `playwright_<browser>dev_profile-` — Playwright's own, created per
+ *    non-persistent `launch()`. These are the orphans measured in #274.
+ *  - `pags-mcp-profile-` — ours, from `McpRuntime` (see mcp-runtime.ts). Chrome
+ *    can rewrite this directory during its async shutdown, after `stop()` has
+ *    already removed it, so it needs a sweeper too.
+ *
+ * A name matching neither is never touched, whatever it contains.
+ */
+const TEMP_PROFILE_NAME = /^(?:playwright_[a-z]+dev_profile|pags-mcp-profile)-[A-Za-z0-9]{6}$/;
+/** Every path the system might hand out as the temp root, de-duplicated. */
+export function tempRoots() {
+    const roots = new Set();
+    for (const root of [tmpdir(), process.env.TMPDIR, "/tmp"]) {
+        if (!root)
+            continue;
+        roots.add(root.replace(/\/+$/, ""));
+    }
+    return [...roots];
+}
+/**
+ * Is this `--user-data-dir` a Playwright throwaway temp profile?
+ *
+ * Both halves matter. The basename pattern says "Playwright mkdtemp'd this"; the
+ * temp-root check says "and it is under the system temp dir, not somewhere a
+ * human keeps a real profile". A directory that satisfies only one is rejected.
+ */
+export function isPlaywrightTempProfile(userDataDir, roots = tempRoots()) {
+    if (!userDataDir)
+        return false;
+    const dir = userDataDir.replace(/\/+$/, "");
+    if (!TEMP_PROFILE_NAME.test(basename(dir)))
+        return false;
+    const parent = dirname(dir).replace(/\/+$/, "");
+    return roots.some((root) => parent === root);
+}
+/** Pull `--user-data-dir=<path>` out of a command line. "" when absent. */
+export function userDataDirOf(command) {
+    // Deliberately `\S+`: every path this reaper acts on is a mkdtemp name under
+    // the temp root, which never contains a space. A path WITH a space therefore
+    // fails to parse and is skipped — the safe direction to be wrong in.
+    const m = command.match(/--user-data-dir=(\S+)/);
+    return m ? m[1] : "";
+}
+/**
+ * Parse `ps -o etime` — `[[DD-]HH:]MM:SS` — into seconds. Returns 0 for anything
+ * unparseable, which reads as "brand new" and therefore never reapable.
+ */
+export function parseEtime(etime) {
+    const trimmed = etime.trim();
+    const m = trimmed.match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
+    if (!m)
+        return 0;
+    const [, days, hours, minutes, seconds] = m;
+    return Number(days ?? 0) * 86400 + Number(hours ?? 0) * 3600 + Number(minutes) * 60 + Number(seconds);
+}
+/** Parse `ps -wwAo pid=,ppid=,etime=,command=` output into candidate rows. */
+export function parsePsOutput(stdout) {
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        const m = line.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const userDataDir = userDataDirOf(m[4]);
+        if (!userDataDir)
+            continue;
+        out.push({ pid: Number(m[1]), ppid: Number(m[2]), ageSeconds: parseEtime(m[3]), userDataDir });
+    }
+    return out;
+}
+/**
+ * Age of a profile directory's last write, in ms.
+ *
+ * A MISSING directory returns Infinity, and that is deliberate rather than a
+ * fallback: Playwright removes this directory only when the browser closed
+ * cleanly. A process still running on a temp profile that no longer exists is
+ * unambiguously abandoned.
+ */
+export function profileIdleMs(dir, now, stat = safeMtimeMs) {
+    const mtime = stat(dir);
+    return mtime === null ? Number.POSITIVE_INFINITY : now - mtime;
+}
+function safeMtimeMs(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The whole safety decision, as one pure function — see the SAFETY block above.
+ * All four conditions must hold; any one of them failing spares the process.
+ */
+export function isReapable(proc, opts) {
+    if (proc.ppid !== 1)
+        return false;
+    if (!isPlaywrightTempProfile(proc.userDataDir, opts.roots))
+        return false;
+    if (proc.ageSeconds * 1000 < opts.minAgeMs)
+        return false;
+    const idle = (opts.idleMs ?? profileIdleMs)(proc.userDataDir, opts.now);
+    return idle >= opts.minAgeMs;
+}
+function ps() {
+    try {
+        // -ww: never truncate the command line, or the --user-data-dir we match on
+        // could be cut off and a real orphan would go unnoticed.
+        return execFileSync("ps", ["-wwAo", "pid=,ppid=,etime=,command="], { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+    }
+    catch {
+        return "";
+    }
+}
+/** Every Playwright-temp-profile browser process currently alive, orphan or not. */
+export function listPlaywrightBrowsers(psOutput = ps()) {
+    return parsePsOutput(psOutput).filter((p) => isPlaywrightTempProfile(p.userDataDir));
+}
+function signal(pid, sig) {
+    try {
+        process.kill(pid, sig);
+    }
+    catch {
+        // already gone, or not ours to signal — either way there is nothing to do
+    }
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Kill abandoned Playwright browsers and delete their temp profiles.
+ *
+ * Synchronous on purpose: this runs once at runner startup, before anything else
+ * competes for the machine, and the whole point is that the CPU is already gone.
+ */
+export function reapOrphanedPlaywrightBrowsers(opts = {}) {
+    const log = opts.log ?? ((line) => console.warn(line));
+    const empty = { reaped: [], skippedYoung: 0 };
+    if (process.platform === "win32")
+        return empty; // no `ps`; the leak is a POSIX-orphan story
+    if (process.pid === 1) {
+        // See SAFETY note 2: as PID 1 we cannot tell an orphan from our own live child.
+        return empty;
+    }
+    const now = opts.now ?? Date.now();
+    const minAgeMs = opts.minAgeMs ?? DEFAULT_MIN_AGE_MS;
+    const all = listPlaywrightBrowsers();
+    const orphanParents = all.filter((p) => p.ppid === 1);
+    const doomed = orphanParents.filter((p) => isReapable(p, { now, minAgeMs }));
+    const skippedYoung = orphanParents.length - doomed.length;
+    if (doomed.length === 0)
+        return { reaped: [], skippedYoung };
+    const dirs = new Set(doomed.map((p) => p.userDataDir));
+    const verb = opts.dryRun ? "would reap" : "reaping";
+    log(`[runner] ${verb} ${doomed.length} abandoned Playwright browser(s) (parent gone, idle >${Math.round(minAgeMs / 60000)}m):`);
+    for (const p of doomed)
+        log(`[runner]   pid ${p.pid}  profile ${p.userDataDir}`);
+    if (opts.dryRun)
+        return { reaped: [...dirs], skippedYoung };
+    // Ask first. The measurement says they ignore it, but a browser that CAN exit
+    // cleanly should be given the chance to flush and remove its own profile.
+    for (const p of doomed)
+        signal(p.pid, "SIGTERM");
+    const deadline = Date.now() + 2000;
+    while (Date.now() < deadline && doomed.some((p) => alive(p.pid))) {
+        // Busy-wait: this is startup, single-purpose, and bounded at 2s. A timer
+        // would need the event loop, and callers want a settled machine on return.
+        execFileSync("sleep", ["0.1"], { stdio: "ignore" });
+    }
+    for (const p of doomed)
+        if (alive(p.pid))
+            signal(p.pid, "SIGKILL");
+    // The renderer/GPU/network helpers are children of the parent we just killed and
+    // normally follow it down. Sweep any that did not, matched by the SAME profile
+    // dirs we already cleared — never by name, never by executable.
+    for (const p of listPlaywrightBrowsers()) {
+        if (dirs.has(p.userDataDir))
+            signal(p.pid, "SIGKILL");
+    }
+    for (const dir of dirs) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // a leftover directory is untidy, not harmful
+        }
+    }
+    return { reaped: [...dirs], skippedYoung };
+}
+/**
+ * Delete Playwright temp profile directories with no live process behind them.
+ *
+ * Separate from the process reap because the two leak independently: a browser
+ * that IS killed by `kill -9` leaves its directory behind with nobody to remove
+ * it. These are a few hundred MB each once they have been used.
+ */
+export function sweepStalePlaywrightProfiles(opts = {}) {
+    if (process.platform === "win32")
+        return [];
+    const now = opts.now ?? Date.now();
+    const minAgeMs = opts.minAgeMs ?? DEFAULT_MIN_AGE_MS;
+    const inUse = new Set(listPlaywrightBrowsers().map((p) => p.userDataDir));
+    const removed = [];
+    for (const root of tempRoots()) {
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (!TEMP_PROFILE_NAME.test(name))
+                continue;
+            const dir = join(root, name);
+            if (inUse.has(dir))
+                continue;
+            if (profileIdleMs(dir, now) < minAgeMs)
+                continue;
+            try {
+                rmSync(dir, { recursive: true, force: true });
+                removed.push(dir);
+            }
+            catch {
+                // best effort
+            }
+        }
+    }
+    if (removed.length > 0) {
+        (opts.log ?? ((l) => console.warn(l)))(`[runner] removed ${removed.length} stale Playwright temp profile dir(s)`);
+    }
+    return removed;
+}
+/**
+ * The startup entry point: recover a machine that has already leaked.
+ *
+ * On by default. Default-off would mean the users who most need it — the ones
+ * whose machine is already at load 253 — never get it, and the discriminator is
+ * narrow enough (see SAFETY) that a false positive would require a real browser
+ * to be running out of a Playwright mkdtemp directory, orphaned, and idle.
+ *   PAGS_RUNNER_REAP=0            disable entirely
+ *   PAGS_RUNNER_REAP_DRY_RUN=1    report what it would kill, kill nothing
+ *   PAGS_RUNNER_REAP_MIN_AGE_MIN  idle threshold in minutes (default 10)
+ */
+export function reapOnStartup(log = (l) => console.warn(l)) {
+    if (process.env.PAGS_RUNNER_REAP === "0")
+        return;
+    const minutes = Number(process.env.PAGS_RUNNER_REAP_MIN_AGE_MIN);
+    const minAgeMs = Number.isFinite(minutes) && minutes > 0 ? minutes * 60_000 : DEFAULT_MIN_AGE_MS;
+    const dryRun = process.env.PAGS_RUNNER_REAP_DRY_RUN === "1";
+    try {
+        const { reaped, skippedYoung } = reapOrphanedPlaywrightBrowsers({ minAgeMs, dryRun, log });
+        if (skippedYoung > 0)
+            log(`[runner] left ${skippedYoung} orphaned browser(s) alone — not idle long enough yet`);
+        if (!dryRun && reaped.length > 0)
+            log(`[runner] reaped ${reaped.length} orphaned browser(s); their CPU is yours again`);
+        if (!dryRun)
+            sweepStalePlaywrightProfiles({ minAgeMs, log });
+    }
+    catch (err) {
+        // Never let cleanup stop the runner from starting.
+        log(`[runner] browser reap skipped: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/browser-runner/runner.js

@@ -180,12 +180,26 @@ export class LocalRunner {
         void this.endTakeover(id).catch(() => undefined);
         return task;
     }
+    /**
+     * Tear everything down, and never let one failure strand the rest (#274).
+     *
+     * `browserContext.close()` rejects routinely — the browser crashed, or was
+     * already killed. It used to reject straight out of here, which skipped the
+     * state reset AND rejected the caller's shutdown, so the process stayed up
+     * holding a live browser until someone `kill -9`ed it. That kill is exactly
+     * what orphans the browser, so an unswallowed error here MADE the leak.
+     */
     async close() {
-        this.coding.closeAll();
+        try {
+            this.coding.closeAll();
+        }
+        catch {
+            // a stuck coding session must not block the browser teardown below
+        }
         await this.mcp?.stop().catch(() => undefined);
         this.mcp = null;
         this.cdpEndpoint = null;
-        await this.browserContext?.close();
+        await this.browserContext?.close().catch(() => undefined);
         this.browserContext = null;
         this.launchedProfileDir = null;
     }

package/package.json

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