@proagentstore/cli 0.4.86 → 0.4.88

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

@@ -12,6 +12,19 @@ const MAX_PANE = 64 * 1024;
 export class CodingRuntime {
     reposBaseDir;
     sessions = new Map();
+    /**
+     * Coding sessions that are running here (#896).
+     *
+     * A Claude session survives a restart — it is re-spawned with `--resume <session_id>` and only
+     * the turn in flight is cut — but a Codex, Grok or raw-engine session restarts cold and its turn
+     * is gone. Both are named, because the owner is the one deciding whether to take the machine.
+     */
+    liveWork() {
+        return [...this.sessions.values()].map((s) => {
+            const engine = s.clientType ?? "";
+            return engine === "claude" ? "a Claude coding session (resumes after a restart)" : `a ${engine || "coding"} turn (lost on a restart)`;
+        });
+    }
     /** Background cold-start clones, one per folder (#858). */
     cloneJobs = new CloneJobs();
     /**

package/dist/browser-runner/index.js

@@ -38,6 +38,12 @@ function configFromArgs() {
         token: arg("--token", process.env.PAGS_RUNNER_TOKEN) || `pags_runner_${randomUUID()}`,
         instanceId: arg("--instance-id", process.env.PAGS_INSTANCE_ID),
         headless: flag("--headless") || process.env.PAGS_RUNNER_HEADLESS === "1",
+        // #896: the single-instance lock's identity and shutdown credential, passed by the parent
+        // (`runner connect`) that took the lock. Absent when nothing holds a lock — a bare
+        // `pags runner start`, or a CLI older than the lock — and then `/control/shutdown` refuses.
+        rsid: process.env.PAGS_RUNNER_RSID || undefined,
+        launch: process.env.PAGS_RUNNER_LAUNCH || undefined,
+        controlNonce: process.env.PAGS_RUNNER_CONTROL_NONCE || undefined,
     };
 }
 if (flag("--help") || flag("-h")) {

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

@@ -167,6 +167,10 @@ function bridgeUnusedHelp(engine, d) {
 export class LocalApplyRuntime {
     deps;
     runs = new Map();
+    /** Application fills that a restart would lose (#896) — their state is in this process. */
+    liveWork() {
+        return [...this.runs.values()].filter((r) => r.state !== "ended").map((r) => `an application fill (${r.envelope.applicationId.slice(0, 8)})`);
+    }
     root;
     now;
     spawn;

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

@@ -111,6 +111,10 @@ class Pause extends Error {
 export class LocalArtifactRuntime {
     deps;
     runs = new Map();
+    /** Tailoring runs that a restart would lose (#896) — their state is in this process. */
+    liveWork() {
+        return [...this.runs.values()].filter((r) => r.state !== "ended").map((r) => `a tailoring run (${r.envelope.runId.slice(0, 8)})`);
+    }
     root;
     now;
     spawn;

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

@@ -148,6 +148,36 @@ export function parseLocalBrowserEvent(raw) {
         event.detail = detail;
     return event;
 }
+/**
+ * A finding, with every free-text part redacted (#947).
+ *
+ * The gap this closes: the result envelope's `summary` and `error` went through {@link redactText}
+ * and its FINDINGS did not. `title`, `evidence` and `detail` were length-capped only, and `fields`
+ * was filtered by KEY ({@link SENSITIVE_KEY}) — so a credential-shaped value under an innocuous key
+ * (`{"note": "sk-ant-api03-…"}`) survived, and a secret environment value quoted into `evidence`
+ * survived verbatim. Both are written by the same CLI, on the same machine, in the same envelope as
+ * the summary that WAS cleaned, and findings are the part that persists furthest: the run's result
+ * row, the console, MCP, and then the owner's own collection record. #947's observability rule —
+ * "do not retain … secret environment values" — was therefore breached on the longest-lived path.
+ *
+ * One definition, used by the runner (which knows the machine's secret env values and passes them)
+ * and again by the API when it parses what arrived (which does not, and catches shapes). Defence in
+ * depth on purpose: the runner is where secrets are knowable, and the cloud is where a runner that
+ * skipped the step is still caught.
+ */
+export function redactFinding(f, secrets = []) {
+    const fields = {};
+    for (const [k, v] of Object.entries(f.fields ?? {})) {
+        if (SENSITIVE_KEY.test(k))
+            continue;
+        fields[k] = typeof v === "string" ? redactText(v, secrets) : v;
+    }
+    return { title: redactText(f.title, secrets), url: f.url, evidence: redactText(f.evidence, secrets), fields };
+}
+/** The same for a source failure's free text; its `reason` is a closed vocabulary and its url is a url. */
+export function redactSourceFailure(f, secrets = []) {
+    return f.detail === undefined ? f : { ...f, detail: redactText(f.detail, secrets) };
+}
 /**
  * A validated result envelope, or the reason it is not one.
  *
@@ -194,7 +224,9 @@ export function parseLocalBrowserResult(raw) {
             else if (typeof v === "number" || typeof v === "boolean" || v === null)
                 fields[k.slice(0, 100)] = v;
         }
-        findings.push({ title, url, evidence, fields });
+        // #947: capped and key-filtered is not redacted. A finding is the longest-lived thing a run
+        // produces, and its free text was the one part of this envelope nothing cleaned.
+        findings.push(redactFinding({ title, url, evidence, fields }));
     }
     const sourceFailures = [];
     for (const [i, f] of o.sourceFailures.entries()) {
@@ -204,7 +236,7 @@ export function parseLocalBrowserResult(raw) {
         if (!url || !reason)
             return { error: `sourceFailures[${i}] needs url and a known reason` };
         const detail = str(r.detail, 1000);
-        sourceFailures.push(detail ? { url, reason, detail } : { url, reason });
+        sourceFailures.push(redactSourceFailure(detail ? { url, reason, detail } : { url, reason }));
     }
     const out = { runId, outcome, findings, sourceFailures, summary: redactText(str(o.summary, LOCAL_BROWSER_CAPS.text) ?? ""), traceId, engineAuth };
     // Redacted again here, whatever the runner did: an error is CLI output, and CLIs print keys.

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

@@ -26,7 +26,7 @@ import { fileURLToPath } from "node:url";
 import { RunnerInputError } from "../errors.js";
 import { BrowserBridge, domainWithin } from "./bridge.js";
 import { BRIDGE_ENV } from "./bridge-stdio.js";
-import { LOCAL_BROWSER_AUTH_MODES, LOCAL_BROWSER_ENGINES, LOCAL_BROWSER_TASK_TYPE, redactDetail, redactText, secretEnvValues, } from "./contract.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";
 /**
  * Why the run could not be launched, in words the owner can act on (#944).
@@ -138,6 +138,15 @@ export function resolveWorkspacePath(path, home) {
 export class LocalBrowserRuntime {
     deps;
     runs = new Map();
+    /**
+     * Research runs that would be LOST if this process stopped (#896).
+     *
+     * Their state is in this process's memory: a restart does not resume them, and the cloud only
+     * gives up on them minutes later. So `--replace` asks before taking the machine.
+     */
+    liveWork() {
+        return [...this.runs.values()].filter((r) => r.state !== "ended").map((r) => `a browser research run (${r.envelope.instanceId.slice(0, 8)})`);
+    }
     root;
     now;
     spawn;
@@ -434,8 +443,11 @@ export class LocalBrowserRuntime {
         run.result = {
             runId: run.envelope.runId,
             outcome: r.outcome,
-            findings: run.bridge?.findings ?? [],
-            sourceFailures: run.bridge?.sourceFailures ?? [],
+            // #947: the machine's own secret env values are knowable HERE and nowhere later, so the
+            // findings are cleaned with them — the same treatment `summary` and `error` below already
+            // had, and the part of this envelope that previously kept whatever the CLI wrote.
+            findings: (run.bridge?.findings ?? []).map((f) => redactFinding(f, run.secrets)),
+            sourceFailures: (run.bridge?.sourceFailures ?? []).map((f) => redactSourceFailure(f, run.secrets)),
             summary: redactText((r.summary ?? "").slice(0, 4000), run.secrets),
             traceId: run.envelope.runId,
             engineAuth: r.engineAuth ?? run.engineAuth,

package/dist/browser-runner/runner.js

@@ -112,6 +112,20 @@ export class LocalRunner {
         if (expired > 0)
             console.log(`[runner] expired ${expired} orphaned in-flight task(s) from a previous session`);
     }
+    /**
+     * What this process is doing that a restart would destroy (#896).
+     *
+     * `close()` stops every local runtime it owns, so "restart the runner" is not a free action: a
+     * Claude coding session resumes, but a Codex or Grok turn, a browser research run, a tailoring
+     * run and an application fill are each lost, and the cloud only reports them `runner_lost`
+     * minutes later. `pags up --replace` reads this and refuses while anything is live unless the
+     * owner passes `--now`, which is the whole reason it is reported rather than counted silently.
+     */
+    liveWork() {
+        const coding = this.coding.liveWork();
+        const local = [...this.localBrowser.liveWork(), ...this.localArtifact.liveWork(), ...this.localApply.liveWork()];
+        return { codingTurns: coding.length, localRuns: local.length, detail: [...coding, ...local].slice(0, 10) };
+    }
     capabilities() {
         return {
             runtime: "pags-browser-runtime",
@@ -255,6 +269,17 @@ export class LocalRunner {
      * 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.
      */
+    /**
+     * Stop because somebody with the lock asked (#896) — the same teardown a signal runs.
+     *
+     * Deliberately not a second shutdown path: `index.ts`'s handler is idempotent and time-boxed
+     * (#274), so raising SIGTERM on ourselves reuses it rather than re-implementing it, which is
+     * what keeps "asked to stop" and "signalled to stop" from drifting apart.
+     */
+    async requestShutdown(reason) {
+        console.log(`[runner] stopping on request (${reason.slice(0, 60)})`);
+        process.kill(process.pid, "SIGTERM");
+    }
     async close() {
         this.localBrowser.closeAll();
         this.localArtifact.closeAll();

package/dist/browser-runner/server.js

@@ -57,6 +57,12 @@ async function route(runner, req, res) {
     const url = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
     const path = url.pathname.replace(/\/$/, "") || "/";
     if ((req.method === "GET" || req.method === "POST") && path === "/health") {
+        // #896: a health check that cannot say WHO answered is not enough to decide anything with.
+        // A contender for the single-instance lock has a pid and a port from the lock file; what it
+        // needs is proof that the process on that port is the one the lock names (`rsid`), and what
+        // `--replace` needs on top of that is what would be destroyed by stopping it (`work`).
+        // Without the id, a recycled port answering "ok" reads as a live holder; without the work
+        // counts, replacing silently ends a Codex turn, a research run or an application fill.
         return json(res, 200, {
             ok: true,
             service: "proagentstore-browser-runtime",
@@ -64,8 +70,36 @@ async function route(runner, req, res) {
             controlPlane: "pags",
             runtimePlane: "pags",
             instanceId: runner.config.instanceId,
+            rsid: runner.config.rsid ?? null,
+            pid: process.pid,
+            launch: runner.config.launch ?? null,
+            work: runner.liveWork(),
         });
     }
+    /**
+     * `POST /control/shutdown` — stop gracefully, when asked by somebody holding the lock (#896).
+     *
+     * This is what makes `pags up --replace` and `pags down` an ASK rather than a kill. The caller
+     * proves it is entitled by quoting the nonce from the mode-600 lock file, which only a process
+     * able to read the owner's own lock can do; `pkill`, which this replaced, proved nothing and
+     * stopped anything matching a name — including another account's runner and a service's.
+     *
+     * The drain itself is `close()`, the same teardown a signal runs, so there is one shutdown path
+     * and not a second one that forgets something.
+     */
+    if (req.method === "POST" && path === "/control/shutdown") {
+        const expected = runner.config.controlNonce ?? "";
+        const body = (await readJson(req).catch(() => null));
+        const given = typeof body?.nonce === "string" ? body.nonce : "";
+        if (!expected || !given || given !== expected)
+            return json(res, 403, { error: "This runner only stops for a request carrying its own lock's nonce." });
+        const work = runner.liveWork();
+        json(res, 202, { stopping: true, pid: process.pid, work });
+        // Answer first, then stop: the caller is waiting for the pid to go, and a reply written
+        // after teardown never arrives.
+        setTimeout(() => void runner.requestShutdown(typeof body?.reason === "string" ? body.reason : "requested"), 10);
+        return;
+    }
     if ((req.method === "GET" || req.method === "POST") && path === "/capabilities") {
         return json(res, 200, runner.capabilities());
     }

package/dist/index.js

@@ -1098,7 +1098,7 @@ var publishCommand = new Command6("publish").description("Publish an agent to Pr
 
 // src/commands/runner/command.ts
 import { spawn as spawn4 } from "child_process";
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { Command as Command7 } from "commander";
 
 // src/commands/runner/process.ts
@@ -1597,7 +1597,16 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
       const [relayRttMs, sessions] = await Promise.all([first ? first.probeRtt() : Promise.resolve(null), readSessionResources(localUrl, runnerToken)]);
       const resources = sampleResources(void 0, void 0, {
         disk: sampleDisk() ?? void 0,
-        runner: { startedAt: processStartedAt, uptimeSec: Math.round(process.uptime()), starts24h, relayReconnects },
+        runner: {
+          startedAt: processStartedAt,
+          uptimeSec: Math.round(process.uptime()),
+          starts24h,
+          relayReconnects,
+          // #896: who is heartbeating. Set by `runner connect` from the lock it took.
+          ...process.env.PAGS_RUNNER_RSID ? { rsid: process.env.PAGS_RUNNER_RSID } : {},
+          pid: process.pid,
+          ...process.env.PAGS_RUNNER_LAUNCH ? { launch: process.env.PAGS_RUNNER_LAUNCH } : {}
+        },
         relayRttMs,
         sessions: sessions ?? void 0
       });
@@ -1853,7 +1862,204 @@ function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, f
   };
 }
 
+// src/runner-lock.ts
+import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { execFileSync as execFileSync2 } from "child_process";
+import { closeSync, mkdirSync as mkdirSync5, openSync, readFileSync as readFileSync6, renameSync, unlinkSync as unlinkSync2, writeSync } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join7 } from "path";
+function configDir(env = process.env) {
+  return env.PAGS_CONFIG_DIR?.trim() || join7(homedir3(), ".config", "proagentstore");
+}
+var accountKey = (account) => createHash("sha256").update(account.trim().toLowerCase()).digest("hex").slice(0, 12);
+var lockPath = (account, env = process.env) => join7(configDir(env), `up-${accountKey(account)}.lock`);
+function classifyHolder(facts) {
+  const lock = facts.lock;
+  if (!lock) return "unknown";
+  if (lock.v !== 1) return "unknown";
+  if (!lock.pid || !Number.isInteger(lock.pid)) return "unknown";
+  if (!facts.pidAlive) return "dead";
+  if (lock.pidStartedAt && facts.pidStartedAt && lock.pidStartedAt !== facts.pidStartedAt) return "dead";
+  if (facts.healthRsid && facts.healthRsid === lock.rsid) return "live";
+  return "unresponsive";
+}
+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 === "headless") return "headless";
+  return lock.launchDetail ? `terminal ${lock.launchDetail}` : "a terminal";
+}
+function holderMessage(lock, verdict) {
+  const since = new Date(lock.startedAt).toLocaleString();
+  const lines = [
+    `A \`pags up\` is already running for this account on this machine.`,
+    `  pid ${lock.pid}, started ${since}, CLI ${lock.version || "?"}, in ${holderWhere(lock)}.`
+  ];
+  if (verdict === "unresponsive") {
+    lines.push(`  It is NOT answering its health check \u2014 it may be asleep, stopped, or the machine may be overloaded.`);
+  }
+  if (verdict === "unknown") {
+    lines.push(`  Its lock file could not be read (a newer CLI may have written it), so it is assumed to be running.`);
+  }
+  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`);
+  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`
+  );
+  return lines;
+}
+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.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() || "" };
+}
+function pidAlive(pid) {
+  if (!pid || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+function pidStartedAt(pid) {
+  if (!pidAlive(pid)) return "";
+  try {
+    if (process.platform === "win32") {
+      const out = execFileSync2("wmic", ["process", "where", `ProcessId=${pid}`, "get", "CreationDate", "/value"], { encoding: "utf-8", timeout: 4e3, stdio: ["ignore", "pipe", "ignore"] });
+      return (out.match(/CreationDate=(\S+)/)?.[1] ?? "").trim();
+    }
+    return execFileSync2("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf-8", timeout: 4e3, stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+}
+async function healthRsid(port, token = "", timeoutMs = 5e3, fetchImpl = fetch) {
+  if (!port) return null;
+  try {
+    const res = await fetchImpl(`http://127.0.0.1:${port}/health`, { headers: token ? { Authorization: `Bearer ${token}` } : {}, signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.rsid === "string" && body.rsid ? body.rsid : null;
+  } catch {
+    return null;
+  }
+}
+function readLock(path) {
+  try {
+    const parsed = JSON.parse(readFileSync6(path, "utf-8"));
+    return parsed && typeof parsed === "object" && typeof parsed.rsid === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function inspectHolder(path, opts = {}) {
+  const lock = readLock(path);
+  if (!lock) return { lock: null, verdict: "unknown" };
+  const alive = pidAlive(lock.pid);
+  const facts = {
+    lock,
+    pidAlive: alive,
+    pidStartedAt: alive ? pidStartedAt(lock.pid) : "",
+    healthRsid: alive ? await healthRsid(lock.port, lock.runnerToken ?? "", opts.healthTimeoutMs ?? 5e3, opts.fetchImpl ?? fetch) : null
+  };
+  return { lock, verdict: classifyHolder(facts) };
+}
+async function acquireLock(input) {
+  const env = input.env ?? process.env;
+  const path = lockPath(input.account, env);
+  const rsid = input.rsid ?? randomUUID2();
+  const handoff = input.handoffFrom?.trim() || env.PAGS_LOCK_HANDOFF?.trim() || "";
+  mkdirSync5(configDir(env), { recursive: true });
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const written = tryWrite(path, buildLock(input, rsid, env));
+    if (written) return { ok: true, lock: written, path, tookOver: attempt === 0 ? "none" : "stale" };
+    const { lock: lock2, verdict: verdict2 } = await inspectHolder(path);
+    if (handoff && lock2?.rsid === handoff) {
+      renameAside(path, lock2.pid);
+      const taken = tryWrite(path, buildLock(input, rsid, env));
+      if (taken) return { ok: true, lock: taken, path, tookOver: "handoff" };
+      continue;
+    }
+    if (!isTakeable(verdict2)) return { ok: false, lock: lock2, path, verdict: verdict2 };
+    if (!takeAsideIfStill(path, lock2?.rsid ?? "", lock2?.pid ?? 0)) continue;
+  }
+  const { lock, verdict } = await inspectHolder(path);
+  return { ok: false, lock, path, verdict };
+}
+function buildLock(input, rsid, env) {
+  const { launch, detail } = detectLaunch(env);
+  const now = Date.now();
+  return {
+    v: 1,
+    rsid,
+    pid: process.pid,
+    pidStartedAt: pidStartedAt(process.pid),
+    startedAt: now,
+    port: input.port,
+    node: input.node,
+    machineId: input.machineId,
+    account: input.account,
+    version: input.version,
+    launch,
+    launchDetail: detail,
+    childPids: [],
+    nonce: randomUUID2(),
+    runnerToken: input.runnerToken ?? "",
+    heartbeatAt: now
+  };
+}
+function tryWrite(path, lock) {
+  let fd = null;
+  try {
+    fd = openSync(path, "wx", 384);
+    writeSync(fd, JSON.stringify(lock, null, 2));
+    return lock;
+  } catch (e) {
+    if (e.code === "EEXIST") return null;
+    throw e;
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+}
+function renameAside(path, pid) {
+  const aside = `${path}.stale-${pid || "unknown"}`;
+  try {
+    renameSync(path, aside);
+    return aside;
+  } catch {
+    return null;
+  }
+}
+function takeAsideIfStill(path, deadRsid, pid) {
+  const aside = renameAside(path, pid);
+  if (!aside) return false;
+  const moved = readLock(aside);
+  if (moved && deadRsid && moved.rsid !== deadRsid) {
+    try {
+      renameSync(aside, path);
+    } catch {
+    }
+    return false;
+  }
+  return true;
+}
+function releaseLock(path, rsid) {
+  const current = readLock(path);
+  if (!current || current.rsid !== rsid) return false;
+  try {
+    unlinkSync2(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/commands/runner/command.ts
+import { hostname as hostname4 } from "os";
 function collectCapability(value, previous = []) {
   return [...previous, value];
 }
@@ -1865,9 +2071,23 @@ function createRunnerCommand() {
     await startRunnerForeground(opts);
   });
   command.command("connect <instanceIds...>").description("Start ONE local runtime, connect via WebSocket relay, and register it for every given PAGS instance").option("--host <host>", "Host to bind", "127.0.0.1").option("--port <port>", "Port to bind", "49171").option("--data-dir <path>", "Runner data directory").option("--token <token>", "Runner bearer token. Defaults to PAGS_RUNNER_TOKEN or a generated token").option("--headless", "Run Playwright headless").option("--api-base <url>", "PAGS API base URL").option("--pags-token <token>", "PAGS session token. Defaults to PAGS_TOKEN").option("--runner-version <version>", "Runner version").option("--force", "Take over from another connected machine").option("--watch-instances", "Attach newly eligible agents while running, without a restart").action(async (instanceIds, opts) => {
-    const runnerToken = clean(opts.token) || clean(process.env.PAGS_RUNNER_TOKEN) || `pags_runner_${randomUUID2()}`;
+    const runnerToken = clean(opts.token) || clean(process.env.PAGS_RUNNER_TOKEN) || `pags_runner_${randomUUID3()}`;
     const host = clean(opts.host) || "127.0.0.1";
     const port = clean(opts.port) || String(await findFreePort2(49171));
+    const lockAccount = clean(process.env.PAGS_LOCK_ACCOUNT) || "";
+    let lockHeld = null;
+    if (lockAccount) {
+      const taken = await acquireLock({ account: lockAccount, node: hostname4(), machineId: loadMachineIdentity().id || null, version: CLI_VERSION, port: Number(port), runnerToken });
+      if (!taken.ok) {
+        for (const line of taken.lock ? holderMessage(taken.lock, taken.verdict) : ["Another `pags up` holds this machine for this account."]) writeError(line);
+        process.exit(1);
+      }
+      lockHeld = { path: taken.path, rsid: taken.lock.rsid, nonce: taken.lock.nonce, launch: taken.lock.launch };
+      writeLine(`STATUS runner-session=${taken.lock.rsid}`);
+    }
+    const releaseHeldLock = () => {
+      if (lockHeld) releaseLock(lockHeld.path, lockHeld.rsid);
+    };
     const localUrl = `http://${host}:${port}`;
     const primary = instanceIds[0];
     const runnerOpts = { ...opts, host, port, token: runnerToken };
@@ -1875,7 +2095,14 @@ function createRunnerCommand() {
     const runner = spawn4(spec.command, spec.args, {
       cwd: spec.cwd,
       stdio: ["ignore", "pipe", "pipe"],
-      shell: process.platform === "win32"
+      shell: process.platform === "win32",
+      // #896: the runtime answers `/health` with the lock's identity and stops for a
+      // request quoting its nonce — so a contender can prove who is on that port, and a
+      // replace is an authorisation rather than a signal aimed at a name pattern.
+      env: {
+        ...process.env,
+        ...lockHeld ? { PAGS_RUNNER_RSID: lockHeld.rsid, PAGS_RUNNER_CONTROL_NONCE: lockHeld.nonce, PAGS_RUNNER_LAUNCH: lockHeld.launch } : {}
+      }
     });
     runner.stdout?.on("data", (data) => process.stdout.write(data));
     runner.stderr?.on("data", (data) => process.stderr.write(data));
@@ -1887,6 +2114,7 @@ function createRunnerCommand() {
     });
     const shutdown = () => {
       shuttingDown = true;
+      releaseHeldLock();
       if (!runner.killed) runner.kill("SIGTERM");
     };
     process.once("exit", shutdown);
@@ -2023,14 +2251,14 @@ function createRunnerCommand() {
 var runnerCommand = createRunnerCommand();
 
 // src/commands/up.ts
-import { execFileSync as execFileSync2 } from "child_process";
+import { execFileSync as execFileSync3 } from "child_process";
 import { createRequire as createRequire2 } from "module";
 import { Command as Command8 } from "commander";
-import { hostname as hostname5 } from "os";
+import { hostname as hostname6 } from "os";
 
 // src/tui.ts
 import chalk from "chalk";
-import { hostname as hostname4 } from "os";
+import { hostname as hostname5 } from "os";
 import readline from "readline";
 var ACCENT = "#7c3aed";
 var c = chalk.hex(ACCENT);
@@ -2083,7 +2311,7 @@ function printStatus(state) {
   clearScreen();
   printLogo(state.version);
   const connected = state.runner === "online" && state.tunnel === "online" && state.registration === "registered";
-  console.log(pad + d("Signed in as ") + w(state.user) + d("  \xB7  agent: ") + w(state.activeInstance) + d("  \xB7  node: ") + w(hostname4()));
+  console.log(pad + d("Signed in as ") + w(state.user) + d("  \xB7  agent: ") + w(state.activeInstance) + d("  \xB7  node: ") + w(hostname5()));
   console.log("");
   const row = (kind, s, override) => {
     const { icon, label, note } = describe(kind, s);
@@ -2145,28 +2373,94 @@ async function waitForKey(keys, onInterrupt) {
   });
 }
 
+// src/runner-replace.ts
+var REPLACE_EXIT_TIMEOUT_MS = 3e4;
+function describeWork(work) {
+  if (work.detail.length) return work.detail.join(", ");
+  const parts = [];
+  if (work.codingTurns) parts.push(`${work.codingTurns} coding turn${work.codingTurns === 1 ? "" : "s"}`);
+  if (work.localRuns) parts.push(`${work.localRuns} local run${work.localRuns === 1 ? "" : "s"}`);
+  return parts.join(", ") || "work";
+}
+var hasWork = (work) => !!work && work.codingTurns + work.localRuns > 0;
+function replaceVerdict(lock, work, opts) {
+  if (lock.launch === "service") {
+    return {
+      allowed: false,
+      lines: [
+        `That runner is managed by a background service${lock.launchDetail ? ` (${lock.launchDetail})` : ""}, so replacing it would only make the service start it again.`,
+        "Stop its launchd/systemd unit instead, then run `pags up` here."
+      ]
+    };
+  }
+  if (hasWork(work) && !opts.now) {
+    return {
+      allowed: false,
+      lines: [
+        `That runner is busy: ${describeWork(work)}.`,
+        "Stopping it now would lose that work \u2014 a Codex or Grok turn, a research run, a tailoring run or an application fill do not survive a restart.",
+        "Wait for it to finish, or run `pags up --replace --now` to stop it anyway."
+      ]
+    };
+  }
+  return { allowed: true, lines: [] };
+}
+async function holderWork(lock, deps = {}) {
+  if (!lock.port) return null;
+  try {
+    const res = await (deps.fetchImpl ?? fetch)(`http://127.0.0.1:${lock.port}/health`, { headers: lock.runnerToken ? { Authorization: `Bearer ${lock.runnerToken}` } : {}, signal: AbortSignal.timeout(5e3) });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const w2 = body.work;
+    if (!w2) return null;
+    const n = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0;
+    return { codingTurns: n(w2.codingTurns), localRuns: n(w2.localRuns), detail: (Array.isArray(w2.detail) ? w2.detail : []).filter((x) => typeof x === "string").slice(0, 10) };
+  } catch {
+    return null;
+  }
+}
+async function replaceHolder(lock, opts = {}, deps = {}) {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const sleep = 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);
+  const verdict = replaceVerdict(lock, work, opts);
+  if (!verdict.allowed) return { ok: false, lines: verdict.lines };
+  if (!lock.port) {
+    return { ok: false, lines: [`The runner holding this machine (pid ${lock.pid}) does not say which port it is on, so it cannot be asked to stop.`, "Stop it where it is running, then try again."] };
+  }
+  try {
+    const res = await fetchImpl(`http://127.0.0.1:${lock.port}/control/shutdown`, {
+      method: "POST",
+      // The runner authorises every request, and the nonce authorises THIS one: the token says
+      // "I may talk to you", the nonce says "I hold your lock" (#896).
+      headers: { "Content-Type": "application/json", ...lock.runnerToken ? { Authorization: `Bearer ${lock.runnerToken}` } : {} },
+      body: JSON.stringify({ nonce: lock.nonce, reason: "replaced" }),
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!res.ok) return { ok: false, lines: [`The runner on pid ${lock.pid} refused the stop request (HTTP ${res.status}).`, "Stop it where it is running, then try again."] };
+  } catch (e) {
+    return { ok: false, lines: [`The runner on pid ${lock.pid} could not be asked to stop: ${e instanceof Error ? e.message : String(e)}.`, "Stop it where it is running, then try again."] };
+  }
+  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);
+  }
+  return {
+    ok: false,
+    lines: [
+      `The runner on pid ${lock.pid} was asked to stop but is still running after ${Math.round(REPLACE_EXIT_TIMEOUT_MS / 1e3)}s.`,
+      "It may be finishing something. Wait and try again, or stop it where it is running \u2014 this command will not kill it for you."
+    ]
+  };
+}
+
 // src/commands/up.ts
 var API_BASE3 = "https://api.proagentstore.online";
 var CLI_VERSION2 = createRequire2(import.meta.url)("../package.json").version;
-async function stopRunnerProcesses() {
-  if (process.platform === "win32") return false;
-  const { execFileSync: execFileSync3 } = await import("child_process");
-  const patterns = [
-    "dist/browser-runner/index.js",
-    "browser-runner/src/index",
-    "runner connect"
-  ];
-  let stopped = false;
-  for (const p of patterns) {
-    try {
-      execFileSync3("pkill", ["-f", p], { stdio: "ignore" });
-      stopped = true;
-    } catch {
-    }
-  }
-  return stopped;
-}
-var upCommand = new Command8("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").action(async (opts) => {
+var upCommand = new Command8("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) => {
   const session = requireSession();
   const state = {
     user: session.user.login,
@@ -2221,7 +2515,7 @@ var upCommand = new Command8("up").description("Start the browser runner for all
     headless: opts.headless
   }).catch(() => void 0);
   if (!opts.instance) {
-    const split = partitionByPin(instances, hostname5(), loadMachineIdentity(hostname5()).names);
+    const split = partitionByPin(instances, hostname6(), loadMachineIdentity(hostname6()).names);
     instances = split.here;
     elsewhere = split.elsewhere;
   }
@@ -2242,7 +2536,26 @@ var upCommand = new Command8("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");
-  await stopRunnerProcesses();
+  const lockFile = lockPath(session.user.login);
+  const held = await inspectHolder(lockFile);
+  if (held.lock && !isTakeable(held.verdict)) {
+    if (!opts.replace) {
+      clearScreen();
+      printLogo(CLI_VERSION2);
+      for (const line of holderMessage(held.lock, held.verdict)) writeLine(`  ${line}`);
+      writeLine("");
+      process.exit(1);
+    }
+    const replaced = await replaceHolder(held.lock, { now: opts.now === true });
+    if (!replaced.ok) {
+      clearScreen();
+      printLogo(CLI_VERSION2);
+      for (const line of replaced.lines) writeLine(`  ${line}`);
+      writeLine("");
+      process.exit(1);
+    }
+    for (const line of replaced.lines) printStep(line, "ok");
+  }
   const { spawn: spawn5 } = await import("child_process");
   const cliPath = process.argv[1];
   const args = [cliPath, "runner", "connect", ...instances.map((i) => i.id)];
@@ -2251,9 +2564,12 @@ var upCommand = new Command8("up").description("Start the browser runner for all
   if (!opts.instance) args.push("--watch-instances");
   const child = spawn5(process.execPath, args, {
     stdio: ["ignore", "pipe", "pipe"],
-    env: { ...process.env, PAGS_TOKEN: session.token, [SUPERVISED_ENV]: SUPERVISOR_RESTARTS }
+    // The child is the lock HOLDER (#896): it owns the relay sockets, so it is what a
+    // contender must find and what `--replace` must be able to stop.
+    env: { ...process.env, PAGS_TOKEN: session.token, [SUPERVISED_ENV]: SUPERVISOR_RESTARTS, PAGS_LOCK_ACCOUNT: session.user.login }
   });
   const logs = [];
+  let childRsid = "";
   const handleOutput = (data2) => {
     const text = data2.toString("utf-8");
     for (const line of text.split("\n")) {
@@ -2261,6 +2577,8 @@ var upCommand = new Command8("up").description("Start the browser runner for all
       if (!trimmed) continue;
       logs.push(trimmed);
       if (logs.length > 200) logs.shift();
+      const rsidLine = trimmed.match(/^STATUS runner-session=(\S+)/);
+      if (rsidLine) childRsid = rsidLine[1];
       const status = parseStatusLine(trimmed);
       if (status) {
         if (status.registration) {
@@ -2319,7 +2637,13 @@ var upCommand = new Command8("up").description("Start the browser runner for all
       return;
     }
     childDead = true;
-    if (code && code !== 0) {
+    if (code === null) {
+      state.runner = "error";
+      state.lastEvent = "Runner stopped by another process (signal) \u2014 it is not connected any more";
+      printStatus(state);
+      return;
+    }
+    if (code !== 0) {
       state.runner = "error";
       state.lastEvent = `Runner exited (code ${code})`;
       const recent = logs.slice(-5);
@@ -2332,7 +2656,7 @@ var upCommand = new Command8("up").description("Start the browser runner for all
     try {
       if (process.stdin.isTTY) process.stdin.setRawMode(false);
       process.stdin.pause();
-      execFileSync2(process.execPath, [process.argv[1], ...restartUpArgs(opts)], { stdio: "inherit", env: { ...process.env, ...env } });
+      execFileSync3(process.execPath, [process.argv[1], ...restartUpArgs(opts)], { stdio: "inherit", env: { ...process.env, ...env } });
     } catch (e) {
       const status = e.status;
       writeLine(`  Restart failed${typeof status === "number" ? ` (exit ${status})` : ""} \u2014 the runner is NOT running. Run 'pags up' again.`);
@@ -2367,26 +2691,37 @@ var upCommand = new Command8("up").description("Start the browser runner for all
       printStatus(state);
     }
     if (key === "r") {
-      if (childDead) restartUp("Restarting runner...");
+      if (childDead) {
+        const other = await inspectHolder(lockFile);
+        if (other.lock && other.lock.rsid !== childRsid && !isTakeable(other.verdict)) {
+          state.lastEvent = `Another \`pags up\` holds this machine (pid ${other.lock.pid}) \u2014 restart refused`;
+          printStatus(state);
+          continue;
+        }
+        restartUp("Restarting runner...");
+      }
       printStatus(state);
     }
   }
 });
-var downCommand = new Command8("down").description("Stop the browser runner and disconnect").action(async () => {
+var downCommand = new Command8("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);
-  if (process.platform === "win32") {
-    writeLine("  On Windows: switch to the 'pags up' window and press Ctrl+C to disconnect.");
+  const session = requireSession();
+  const lock = readLock(lockPath(session.user.login));
+  if (!lock) {
+    writeLine("  No runner of yours is running on this machine \u2014 nothing to stop.");
     writeLine("");
     return;
   }
-  const stopped = await stopRunnerProcesses();
-  if (stopped) {
+  const stopped = await replaceHolder(lock, { now: opts.now === true });
+  if (stopped.ok) {
+    releaseLock(lockPath(session.user.login), lock.rsid);
     writeLine("  \u2713 Runner stopped \u2014 you're disconnected.");
     writeLine("");
     writeLine("  Your agent won't act on the web until you run 'pags up' again.");
   } else {
-    writeLine("  No runner was running \u2014 nothing to stop.");
+    for (const line of stopped.lines) writeLine(`  ${line}`);
   }
   writeLine("");
 });

package/package.json

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