@proagentstore/cli 0.4.34 → 0.4.36

package/dist/browser-runner/coding/engine-acts.js

@@ -0,0 +1,199 @@
+/**
+ * What the Engine actually DID — the consequential-act record (#294).
+ *
+ * A delegated run recorded its objective and its terminal outcome and nothing in between. Live,
+ * run `73ffc073` merged its own PRs to `main` unattended and the supervisor view said "done". For
+ * a read-only goal that is fine; for a goal that merges to the trunk it is trust, not review.
+ *
+ * ── WHERE THE SIGNAL COMES FROM, AND WHY IT IS NOT THE OTHER ONE ──
+ *
+ * The obvious alternative was a repo-state delta: snapshot branch/HEAD/refs before and after a run
+ * and diff them. #276 already reads `git status --short --branch` through the runner, so it is
+ * nearly free. It was rejected on a fact, not a preference: **a pull request is not a git object.**
+ * `gh pr create` changes nothing in the local repository at all, and `gh pr merge` changes a ref on
+ * GitHub that the local checkout does not learn about until somebody fetches. So the delta design
+ * cannot satisfy the one thing the issue asks for by name — "a run that opens or merges a PR leaves
+ * a record naming that act" — and would report a clean tree on `main` for the exact run that
+ * prompted the issue.
+ *
+ * What it CAN see (branch moved, tree dirty) is already reported by #276, so building it here would
+ * have duplicated the covered half and missed the uncovered one.
+ *
+ * The worry the issue actually raises about this side — "parsing terminal output is unreliable, the
+ * model's prose is not an audit trail" — does not apply to what is parsed here. This does not read
+ * the Engine's prose. Claude Code's stream-json protocol emits a `tool_use` block per tool
+ * invocation carrying the literal command string it is about to run, and a `tool_result` carrying
+ * whether it failed. `{"command":"gh pr merge 42 --squash"}` is a protocol event, the same class of
+ * fact as the `result` event #267 takes its cost figures from. It is what the Engine RAN, not what
+ * it later said about what it ran.
+ *
+ * ── THE HONEST GAP ──
+ *
+ * Only a stream-json engine (Claude Code) produces these. A raw Codex/Grok session emits nothing
+ * parseable, so it records no acts — the same gap, for the same reason, as engine usage (#267). An
+ * empty act list therefore means "nothing observed", never "nothing happened", and every consumer
+ * has to say so rather than render it as an all-clear.
+ */
+/** Acts whose consequences reach outside the machine, or cannot be walked back locally. */
+const IRREVERSIBLE = new Set([
+    "pr.merge",
+    "push.trunk",
+    "push.force",
+    "branch.delete",
+    "reset.hard",
+    "clean",
+    "file.delete",
+    "release.publish",
+    "package.publish",
+    "repo.delete",
+    "deploy",
+]);
+/** Hard cap on the recorded command text. Long enough to read, short enough not to be a log dump. */
+const MAX_COMMAND = 400;
+/**
+ * Strip anything that looks like a credential before the command is stored or shown.
+ *
+ * A command line is the single most common place a token is pasted in the open
+ * (`GH_TOKEN=… git push`, `https://x-access-token:…@github.com/…`), and this record travels from
+ * the user's machine into D1 and then into a supervisor's model prompt. Redacting at the point of
+ * capture is the only place that covers all three.
+ */
+export function redactCommand(command) {
+    let s = String(command ?? "");
+    // Credentials embedded in a clone/push URL.
+    s = s.replace(/(https?:\/\/)[^/\s@]+@/g, "$1***@");
+    // Known token shapes, whatever they are assigned to.
+    s = s.replace(/\b(gh[pousr]_|github_pat_)[A-Za-z0-9_]{10,}/g, "$1***");
+    s = s.replace(/\bsk-[A-Za-z0-9_-]{16,}/g, "sk-***");
+    s = s.replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, "xox-***");
+    // Anything ASSIGNED to a secret-shaped name, whatever the value looks like.
+    s = s.replace(/\b([A-Za-z_][A-Za-z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|APIKEY|API_KEY|KEY|PAT))=(\S+)/gi, "$1=***");
+    return s.trim().slice(0, MAX_COMMAND);
+}
+/**
+ * Split a shell command into the pieces that each run something.
+ *
+ * Deliberately aggressive — `&&`, `||`, `;`, `|` and newlines all split, regardless of quoting.
+ * Over-splitting costs nothing (a fragment simply matches no rule); under-splitting loses an act,
+ * and the real-world shape of the case this exists for is exactly a compound line:
+ * `cd repo && git push -u origin fix && gh pr create --fill && gh pr merge --squash`.
+ */
+export function splitSegments(command) {
+    return String(command ?? "")
+        .split(/\|\||&&|[;|\n]/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** A token that is exactly the trunk, not a branch merely containing the word (`feature/main-fix`). */
+const TRUNK_TOKEN = /(?:^|\s)(?:HEAD:)?(?:refs\/heads\/)?(?:main|master)(?:\s|$)/;
+function prRef(segment) {
+    // `gh pr merge 42 --squash`, `gh pr merge --squash 42`, or a full URL.
+    const url = segment.match(/https?:\/\/\S*?\/pull\/(\d+)/);
+    if (url)
+        return `#${url[1]}`;
+    const num = segment.match(/\bgh\s+pr\s+(?:merge|create)\b(?:\s+-{1,2}\S+(?:=\S+)?)*\s+(\d+)\b/);
+    return num ? `#${num[1]}` : null;
+}
+function pushTarget(segment) {
+    // `git push [flags] <remote> <refspec>` — take the first two non-flag words after `push`.
+    const after = segment.split(/\bgit\s+push\b/)[1] ?? "";
+    const words = after.split(/\s+/).filter((w) => w && !w.startsWith("-"));
+    return words.length ? words.slice(0, 2).join(" ") : null;
+}
+/**
+ * Classify ONE shell segment. Returns null for ordinary work, which is nearly everything.
+ *
+ * The rules are matched in order of consequence, so `git push --force origin main` is recorded as
+ * the force-push it is rather than as an ordinary push.
+ */
+export function classifySegment(segment) {
+    const s = String(segment ?? "");
+    const hit = (kind, target = null) => ({
+        kind,
+        target,
+        irreversible: IRREVERSIBLE.has(kind),
+    });
+    if (/\bgh\s+pr\s+merge\b/.test(s))
+        return hit("pr.merge", prRef(s));
+    if (/\bgh\s+pr\s+create\b/.test(s))
+        return hit("pr.open", prRef(s));
+    if (/\bgh\s+release\s+create\b/.test(s))
+        return hit("release.publish");
+    if (/\bgh\s+repo\s+delete\b/.test(s))
+        return hit("repo.delete");
+    if (/\bgit\s+push\b/.test(s)) {
+        if (/(?:^|\s)(?:--force|--force-with-lease|-f)(?:=|\s|$)/.test(s))
+            return hit("push.force", pushTarget(s));
+        // `git push origin --delete x` and the older `git push origin :x` both delete a REMOTE
+        // branch — the one push that destroys rather than adds.
+        if (/(?:^|\s)--delete(?:\s|$)/.test(s) || /\s:\S+/.test(s))
+            return hit("branch.delete", pushTarget(s));
+        if (TRUNK_TOKEN.test(s.split(/\bgit\s+push\b/)[1] ?? ""))
+            return hit("push.trunk", pushTarget(s));
+        return hit("push", pushTarget(s));
+    }
+    // `-d` as well as `-D`: a supervisor asking "what did it delete" does not care that one of them
+    // refused on unmerged commits.
+    if (/\bgit\s+branch\s+(?:-\S*[dD]\b|--delete\b)/.test(s))
+        return hit("branch.delete");
+    if (/\bgit\s+reset\s+(?:\S+\s+)*--hard\b/.test(s))
+        return hit("reset.hard");
+    if (/\bgit\s+clean\b[^\n]*(?:^|\s)-\S*[fdx]/.test(s))
+        return hit("clean");
+    // Only a RECURSIVE or FORCED rm. Plain `rm scratch.txt` is housekeeping, and recording it would
+    // bury the acts that matter under noise — the record is only useful if it stays dense.
+    if (/\brm\s+(?:\S+\s+)*-\S*[rf]/.test(s))
+        return hit("file.delete");
+    if (/\b(?:npm|pnpm|yarn|bun)\s+publish\b/.test(s))
+        return hit("package.publish");
+    if (/\bwrangler\s+(?:\S+\s+)*deploy\b/.test(s))
+        return hit("deploy");
+    if (/\b(?:vercel|netlify)\s+(?:\S+\s+)*deploy\b/.test(s))
+        return hit("deploy");
+    if (/\bvercel\b[^\n]*--prod\b/.test(s))
+        return hit("deploy");
+    return null;
+}
+/**
+ * Classify a whole command into zero or more acts.
+ *
+ * `id` is the engine's `tool_use` id; a compound command yielding two acts gets `id:0`/`id:1` so
+ * each still has its own stable dedup key. Every act carries the FULL original command as evidence,
+ * not just the segment that matched — a supervisor reading "force-pushed" needs to see what else
+ * was on that line.
+ */
+export function classifyCommand(id, command, at = new Date().toISOString()) {
+    const full = redactCommand(command);
+    if (!full)
+        return [];
+    const out = [];
+    for (const seg of splitSegments(command)) {
+        const c = classifySegment(seg);
+        if (!c)
+            continue;
+        out.push({
+            id: `${id}:${out.length}`,
+            kind: c.kind,
+            command: full,
+            target: c.target,
+            irreversible: c.irreversible,
+            ok: null,
+            at,
+        });
+    }
+    return out;
+}
+/**
+ * Pull the command string out of a `tool_use` block's input.
+ *
+ * Keyed on the INPUT SHAPE rather than the tool name: Claude Code calls it `Bash`, but a session
+ * launched with a custom agent/tool set can present the same shell capability under another name,
+ * and matching the name would silently record nothing for it. Anything handing a tool a `command`
+ * string is running a command.
+ */
+export function commandFromToolInput(input) {
+    if (!input || typeof input !== "object")
+        return null;
+    const cmd = input.command;
+    return typeof cmd === "string" && cmd.trim() ? cmd : null;
+}

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

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { classifyCommand, commandFromToolInput } from "./engine-acts.js";
 import { parseEngineUsage } from "./engine-usage.js";
 /**
  * Merge the platform's resolved engine env over the machine's, where an EMPTY value means
@@ -33,6 +34,16 @@ import { resolveEngineAuth } from "./engine-auth.js";
  * (refusing new records) would lose the turns that just happened rather than ancient ones.
  */
 const MAX_PENDING_USAGE = 200;
+/**
+ * How many un-drained consequential acts a session holds (#294).
+ *
+ * Smaller than the usage cap because acts are rare by construction — an ordinary turn produces
+ * none — so filling this means something has gone very wrong (a loop force-pushing repeatedly),
+ * and in that case the FIRST ones are the ones that explain it. So this cap drops the NEWEST rather
+ * than the oldest, the opposite of the usage queue: a spend record is fungible and the recent ones
+ * matter most, whereas the merge that started an incident is the one you cannot afford to lose.
+ */
+const MAX_PENDING_ACTS = 100;
 export class HeadlessSession {
     config;
     /**
@@ -66,6 +77,20 @@ export class HeadlessSession {
     stopped = false;
     /** Measured engine spend not yet handed to the cloud (#267). Drained by {@link takeUsage}. */
     pendingUsage = [];
+    /**
+     * Consequential acts observed but not yet handed to the cloud (#294). Drained by
+     * {@link takeActs}.
+     */
+    pendingActs = [];
+    /**
+     * Acts whose `tool_result` has not come back yet, keyed by the engine's `tool_use` id.
+     *
+     * They are held here rather than published immediately so the record can say whether the
+     * command SUCCEEDED. A `gh pr merge` that failed on a branch-protection rule, published as a
+     * merge, would put an unattended merge to `main` in the audit trail that never happened — which
+     * damages the record exactly as much as missing a real one.
+     */
+    awaitingResult = new Map();
     /** Turn counter — only used to build a fallback id when the CLI's event has no `uuid`. */
     usageSeq = 0;
     /**
@@ -77,6 +102,18 @@ export class HeadlessSession {
      * The queue is in memory and dies with the process, so a salt can never cause a double-count.
      */
     usageRunId = Math.random().toString(36).slice(2, 10);
+    /** Fallback counter for an act whose `tool_use` block carries no id of its own. */
+    actSeq = 0;
+    /**
+     * Per-PROCESS salt for act ids, for the same reason as {@link usageRunId}.
+     *
+     * Claude Code's `tool_use` ids are unique within a conversation, not across restarts. Without a
+     * salt, a resumed session could re-emit an id the cloud has already written, and the
+     * conflict-ignoring insert would silently drop the SECOND act — a real merge, discarded because
+     * an older one happened to share an id. The queue is in memory and dies with the process, so a
+     * salt can never cause a double-write.
+     */
+    actsRunId = Math.random().toString(36).slice(2, 10);
     /**
      * The engine binary could not be spawned (ENOENT, not executable).
      *
@@ -456,13 +493,16 @@ export class HeadlessSession {
                     }
                     else if (block.type === "tool_use") {
                         this.push(`⚙ ${String(block.name ?? "tool")} ${shortInput(block.input)}`); // ⚙
+                        this.noteAct(block);
                     }
                 }
                 break;
             case "user": // tool results come back as a synthetic user message
                 for (const block of ev.message?.content ?? []) {
-                    if (block.type === "tool_result")
+                    if (block.type === "tool_result") {
                         this.push(`  ↳ ${toolResult(block.content)}`); // ↳
+                        this.settleAct(block);
+                    }
                 }
                 break;
             case "result": {
@@ -477,6 +517,11 @@ export class HeadlessSession {
                     if (this.pendingUsage.length > MAX_PENDING_USAGE)
                         this.pendingUsage.shift();
                 }
+                // The turn ended, so no further `tool_result` is coming for anything still waiting.
+                // Publish it with an UNKNOWN outcome rather than dropping it: "it ran this and we
+                // never saw whether it worked" is a materially different claim from silence, and
+                // silence is what a supervisor would read as "it did nothing".
+                this.flushAwaitingActs();
                 this.run = "idle"; // the turn is OVER — a fact, not a guess
                 break;
             }
@@ -490,6 +535,62 @@ export class HeadlessSession {
     push(line) {
         this.transcript.push(line);
     }
+    /**
+     * A `tool_use` block just went past — record it if the command it carries is consequential
+     * (#294). Nearly every call classifies to nothing and costs one regex sweep.
+     */
+    noteAct(block) {
+        const command = commandFromToolInput(block.input);
+        if (!command)
+            return;
+        const toolUseId = typeof block.id === "string" && block.id ? block.id : `${this.config.id}:${this.actSeq++}`;
+        const acts = classifyCommand(`${this.actsRunId}:${toolUseId}`, command);
+        if (!acts.length)
+            return;
+        this.awaitingResult.set(toolUseId, acts);
+    }
+    /** The matching `tool_result` arrived — stamp the outcome and publish. */
+    settleAct(block) {
+        const id = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+        const acts = this.awaitingResult.get(id);
+        if (!acts)
+            return;
+        this.awaitingResult.delete(id);
+        const ok = block.is_error !== true;
+        for (const a of acts)
+            this.publishAct({ ...a, ok });
+    }
+    /** Publish everything still waiting, with an unknown outcome. */
+    flushAwaitingActs() {
+        for (const acts of this.awaitingResult.values()) {
+            for (const a of acts)
+                this.publishAct(a);
+        }
+        this.awaitingResult.clear();
+    }
+    publishAct(act) {
+        // Drops the NEWEST at the cap — see MAX_PENDING_ACTS for why this queue is the opposite
+        // way round from the usage one.
+        if (this.pendingActs.length >= MAX_PENDING_ACTS)
+            return;
+        this.pendingActs.push(act);
+    }
+    /**
+     * Hand over the consequential acts seen since the last drain, and forget them (#294).
+     *
+     * Drained rather than re-reported for the same reason as {@link takeUsage}: a 3s capture poll
+     * must not re-send the same merge forever. The cloud's insert is keyed on
+     * {@link EngineActRecord.id}, so the genuine race — the console's poll and the Pilot's own
+     * capture draining at the same moment — still cannot write the act twice.
+     *
+     * A raw engine returns an empty array, always. Nothing parses its stdout, so it has nothing to
+     * hand over; an empty list here means "not observed", never "nothing happened".
+     */
+    takeActs() {
+        const out = this.pendingActs;
+        this.pendingActs = [];
+        return out;
+    }
     /**
      * Hand over the measured spend since the last drain, and forget it (#267).
      *

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

@@ -110,7 +110,7 @@ export class CodingRuntime {
             // exactly the question asked about a session that just stopped.
             authResolved: session.authResolved,
             engineRuntime: session.engineRuntime,
-            ...(opts.drainUsage ? { usage: session.takeUsage() } : {}),
+            ...(opts.drainUsage ? { usage: session.takeUsage(), acts: session.takeActs() } : {}),
         };
     }
     /** Perform one action, then return the fresh snapshot (non-blocking, like browser act). */
@@ -143,12 +143,17 @@ export class CodingRuntime {
     end(sessionId) {
         const session = this.sessions.get(sessionId);
         const usage = session ? session.takeUsage() : [];
+        // Acts drain here too, and for a sharper version of the same reason (#294): the LAST thing a
+        // coding run does is very often the consequential one — push, open the PR, merge it — and it
+        // happens after the final capture poll. Discarding the tail would systematically lose exactly
+        // the acts this record exists for.
+        const acts = session ? session.takeActs() : [];
         if (session) {
             session.stop();
             this.sessions.delete(sessionId);
         }
         this.takeovers.delete(sessionId);
-        return { ok: true, usage };
+        return { ok: true, usage, acts };
     }
     list() {
         return [...this.sessions.entries()].map(([sessionId, s]) => ({

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/dist/browser-runner/test-job-server.js

@@ -21,6 +21,17 @@ export async function startTestJobServer(port = 0) {
         async close() {
             await new Promise((resolve, reject) => {
                 server.close((error) => (error ? reject(error) : resolve()));
+                // `close()` stops ACCEPTING connections; it does not end the open ones, and
+                // its callback does not fire until the last socket goes away. A Playwright
+                // browser that navigated here keeps its connection alive for reuse, so the
+                // callback waited on a socket only the browser would ever close — an
+                // UNBOUNDED wait, not a slow one.
+                //
+                // That is why this could not be fixed by raising a budget, and two attempts
+                // tried: bc3f2b3 bounded `mcp.stop()`, f3e9c53 raised `hookTimeout`. The hook
+                // still burned its whole budget, red-gated CI, and blocked the API deploy on
+                // main for unrelated commits that happened to land next.
+                server.closeAllConnections();
             });
         },
     };

package/package.json

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