@proagentstore/cli 0.4.61 → 0.4.63

package/dist/bootstrap.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bootstrap.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import {
+  BOOTSTRAP_ENV,
+  NO_SELF_UPDATE_ENV,
+  cachedPayloads,
+  installPayload,
+  latestPublishedVersion,
+  newestPayload,
+  olderThan,
+  payloadAt
+} from "./chunk-JOWYSZOL.js";
+
+// src/bootstrap.ts
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+// src/bootstrap/stub.ts
+import { pathToFileURL } from "url";
+function checksForUpdate(args) {
+  return args.find((a) => !a.startsWith("-")) === "up";
+}
+async function runStub(deps) {
+  const log = deps.log ?? ((line) => process.stderr.write(`${line}
+`));
+  const local = () => newestPayload([...deps.bundled ? [deps.bundled] : [], ...(deps.cached ?? cachedPayloads)()]);
+  let chosen = local();
+  if (checksForUpdate(deps.args) && !deps.fromSource && process.env[NO_SELF_UPDATE_ENV] !== "1") {
+    const latest = await (deps.latest ?? (() => latestPublishedVersion(15e3)))();
+    if (latest && (!chosen || olderThan(chosen.version, latest))) {
+      log(`pags: updating ${chosen?.version ?? "(none)"} \u2192 ${latest}\u2026`);
+      try {
+        chosen = await (deps.install ?? ((v) => installPayload(v)))(latest);
+        log(`pags: now on ${chosen.version}`);
+      } catch (e) {
+        log(`pags: could not fetch ${latest} (${e instanceof Error ? e.message : String(e)}) \u2014 starting ${chosen?.version ?? "nothing"} instead`);
+      }
+    }
+  }
+  if (!chosen) throw new Error("pags: no CLI to run \u2014 reinstall with `npm i -g @proagentstore/cli`");
+  process.env[BOOTSTRAP_ENV] = deps.self;
+  await (deps.load ?? ((entry) => import(pathToFileURL(entry).href)))(chosen.entry);
+  return chosen;
+}
+
+// src/bootstrap.ts
+var self = fileURLToPath(import.meta.url);
+var packageDir = join(dirname(self), "..");
+try {
+  await runStub({
+    bundled: payloadAt(packageDir),
+    args: process.argv.slice(2),
+    self,
+    fromSource: existsSync(join(packageDir, "src", "bootstrap.ts"))
+  });
+} catch (e) {
+  process.stderr.write(`${e instanceof Error ? e.message : String(e)}
+`);
+  process.exit(1);
+}

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

@@ -1,3 +1,4 @@
+import { stripAnsi } from "./transcript-lines.js";
 export function engineInvocationModeFromAdapter(mode) {
     return mode === "stream-json" ? "structured" : "raw";
 }
@@ -5,7 +6,7 @@ export function structuredCapableEngine(clientType) {
     return clientType === "claude" || clientType === "codex";
 }
 export function engineInvocationWarning(clientType, mode) {
-    if (mode !== "raw" || clientType !== "claude")
+    if (mode !== "raw" || !structuredCapableEngine(clientType))
         return null;
     return `running raw — structured not available on this machine's ${clientType} CLI`;
 }
@@ -113,6 +114,31 @@ function buildCodexExecArgs(userArgs, turnText) {
     args.push(turnText);
     return args;
 }
+/**
+ * The only supported runner-owned Codex continuity form (#848).
+ *
+ * `exec resume` takes the thread id between the subcommand and the prompt, so it cannot use the
+ * normal preset-prefix-plus-final-prompt contract. Its write flag is deliberately not inherited
+ * from a fresh `exec`: resume accepts the bypass flag but does not accept `--sandbox <mode>`.
+ * This remains an opaque, machine-local optimisation until #693's platform timeline owns the
+ * conversation; it must never select a conversation with `--last`.
+ */
+export function buildCodexResumeArgs(userArgs, threadId, turnText) {
+    const extras = [];
+    for (let i = 1; i < userArgs.length; i++) {
+        const arg = userArgs[i];
+        if (arg === "--json" || arg === "--dangerously-bypass-approvals-and-sandbox")
+            continue;
+        if (arg === "--sandbox") {
+            i++;
+            continue;
+        }
+        if (arg.startsWith("--sandbox="))
+            continue;
+        extras.push(arg);
+    }
+    return ["exec", "resume", threadId, "--json", "--dangerously-bypass-approvals-and-sandbox", ...extras, turnText];
+}
 function parseCodexLine(line) {
     let ev;
     try {
@@ -163,12 +189,24 @@ function parseCodexLine(line) {
         return [{ kind: "tool_use", block, id, name: "Bash", input: { command } }];
     return [];
 }
+/**
+ * An older Codex CLI exits before doing work when it does not know `--json`. Do not treat every
+ * plain line as a downgrade signal: current Codex can interleave malformed/tool stderr with valid
+ * JSONL, and retrying after that could run a real instruction twice.
+ */
+function codexRejectsJson(line) {
+    const plain = stripAnsi(line).toLowerCase();
+    if (!plain.includes("--json"))
+        return false;
+    return /(?:unexpected argument|unknown (?:argument|option)|unrecognized (?:argument|option)|invalid option)/.test(plain);
+}
 export const codexEngineAdapter = {
     mode: "stream-json",
     persistent: false,
     buildLaunchArgs: (userArgs) => [...userArgs],
     buildTurnArgs: buildCodexExecArgs,
     parseLine: parseCodexLine,
+    rejectsStructuredOutput: codexRejectsJson,
 };
 export const genericRawEngineAdapter = {
     mode: "raw",

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

@@ -0,0 +1,50 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Codex CLI emitted UUID-shaped `thread_id`s in the #730 proof; reject anything unsafe to argv. */
+export function isCodexThreadId(value) {
+    return typeof value === "string" && /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(value);
+}
+function stateKey(id, engine) {
+    return engine === "codex" ? `codex:${id}` : id;
+}
+function loadFile(path) {
+    if (!path || !existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        return Object.fromEntries(Object.entries(parsed).flatMap(([key, value]) => (typeof value === "string" && value.trim() ? [[key, value]] : [])));
+    }
+    catch {
+        return {};
+    }
+}
+export function readState(path, id, engine) {
+    return loadFile(path)[stateKey(id, engine)] ?? null;
+}
+export function readCodexState(path, id) {
+    const threadId = readState(path, id, "codex");
+    return isCodexThreadId(threadId) ? threadId : null;
+}
+export function writeState(path, id, sessionId, engine) {
+    if (!path)
+        return;
+    try {
+        const data = loadFile(path);
+        const key = stateKey(id, engine);
+        if (sessionId)
+            data[key] = sessionId;
+        else
+            delete data[key];
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(data));
+    }
+    catch {
+        /* best-effort persistence */
+    }
+}
+/** Default location for the resume-id store, under the repos base dir. */
+export function defaultStatePath(reposBaseDir) {
+    return join(reposBaseDir, "headless-sessions.json");
+}

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

@@ -6,12 +6,12 @@ import { renderToolResult, shortInput, stripAnsi } from "./transcript-lines.js";
 import { authoredTurn, authorTag } from "./turn-author.js";
 import { engineSpawnEnv, mergeEnv } from "./engine-env.js";
 import { ghGuardStatus } from "./gh-guard.js";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
 import { handlerFor } from "./handlers.js";
 import { resolveEngineAuth } from "./engine-auth.js";
-import { engineAdapterFor, engineInvocationModeFromAdapter, engineInvocationWarning } from "./engine-adapter.js";
+import { buildCodexResumeArgs, engineAdapterFor, engineInvocationModeFromAdapter, engineInvocationWarning, genericRawEngineAdapter } from "./engine-adapter.js";
+import { isCodexThreadId, readCodexState, readState, writeState } from "./headless-state.js";
 export { buildClaudeArgs } from "./engine-adapter.js";
+export { defaultStatePath } from "./headless-state.js";
 /**
  * How many un-drained usage records a session holds (#267).
  *
@@ -62,6 +62,8 @@ export class HeadlessSession {
     run = "idle";
     /** Claude Code's own session id (from the init event) — used to --resume. */
     claudeSessionId = null;
+    /** Codex's thread id from `thread.started` — used only by the explicit-ID resume path (#848). */
+    codexThreadId = null;
     /**
      * The cloud's context brief, until the first turn spends it (ADR 0005, #693). Null once
      * delivered, and null from the start when the engine resumed its own conversation.
@@ -96,6 +98,12 @@ export class HeadlessSession {
      * carry a previous turn's line.
      */
     turnLastLine = "";
+    /** True once this session has retried an old Codex CLI without its unsupported `--json` flag. */
+    fellBackToRaw = false;
+    /** Structured events observed in the current one-shot process. */
+    sawStructuredEvent = false;
+    /** A Codex CLI explicitly rejected the `--json` flag in the current one-shot process. */
+    structuredOutputRejected = false;
     /** Measured engine spend not yet handed to the cloud (#267). Drained by {@link takeUsage}. */
     pendingUsage = [];
     /**
@@ -196,11 +204,13 @@ export class HeadlessSession {
      * clean, so a cloud that announced "resumed where we left off" on its own intent would be
      * telling most of the fleet's users the opposite of what happened.
      *
-     * False for a raw (non-Claude) engine under every circumstance — `--resume` is a Claude Code
-     * flag and {@link buildClaudeArgs} is only reached in stream-json mode.
+     * False for raw engines. Claude has a persistent protocol-level resume; supported structured
+     * `codex exec` uses the separately proven explicit-ID one-shot path (#848), only as the
+     * machine-local stopgap before #693's platform-owned timeline becomes authoritative.
      */
     get resumedConversation() {
-        return this.config.clientType === "claude" && this.mode === "stream-json" && this.claudeSessionId !== null;
+        return ((this.config.clientType === "claude" && this.mode === "stream-json" && this.claudeSessionId !== null) ||
+            (this.config.clientType === "codex" && this.mode === "stream-json" && this.codexThreadId !== null));
     }
     /**
      * Did this engine come up cold AND with a brief to lead its first turn (ADR 0005, #693)?
@@ -216,11 +226,6 @@ export class HeadlessSession {
     constructor(config) {
         this.config = config;
         this.engineLabel = `${config.clientType}:${config.id}`;
-        // Our own key first, the cloud's nominated predecessor second. See `resumeFrom`.
-        this.claudeSessionId =
-            config.clientType === "claude"
-                ? readState(config.statePath, config.id) ?? (config.resumeFrom ? readState(config.statePath, config.resumeFrom) : null)
-                : null;
         const { bin, args } = parseCommand(config.command);
         // When no explicit command is configured, fall back to THIS engine's default
         // command (codex/gemini/grok/…) — not a hard-coded "claude", which would drive a
@@ -233,6 +238,16 @@ export class HeadlessSession {
         this.cmdArgs = bin ? args : fallback.args;
         this.adapter = engineAdapterFor(config.clientType, this.cmdArgs);
         this.mode = this.adapter.mode;
+        // Our own key first, the cloud's nominated predecessor second. See `resumeFrom`. Codex uses
+        // a distinct key namespace: a vendor thread id is not interchangeable with Claude's id.
+        this.claudeSessionId =
+            config.clientType === "claude"
+                ? readState(config.statePath, config.id, "claude") ?? (config.resumeFrom ? readState(config.statePath, config.resumeFrom, "claude") : null)
+                : null;
+        this.codexThreadId =
+            config.clientType === "codex" && this.mode === "stream-json"
+                ? readCodexState(config.statePath, config.id) ?? (config.resumeFrom ? readCodexState(config.statePath, config.resumeFrom) : null)
+                : null;
         // AFTER both lines above, because `resumedConversation` reads them: the brief is the fallback,
         // so an engine that found its own conversation drops it unread rather than being handed a
         // summary of the conversation it is already in.
@@ -409,7 +424,7 @@ export class HeadlessSession {
             // start is a clean session rather than looping on a dead id.
             if (code && code !== 0 && this.claudeSessionId) {
                 this.claudeSessionId = null;
-                writeState(this.config.statePath, this.config.id, null);
+                writeState(this.config.statePath, this.config.id, null, "claude");
             }
         });
     }
@@ -473,7 +488,13 @@ export class HeadlessSession {
         // Arm the per-turn line capture BEFORE the spawn, so a report can only ever carry a line
         // this turn produced (#545).
         this.turnLastLine = "";
-        const proc = spawn(this.cmdBin, this.adapter.buildTurnArgs(this.cmdArgs, text), {
+        this.sawStructuredEvent = false;
+        this.structuredOutputRejected = false;
+        const resumedCodexThreadId = this.codexResumeThreadId;
+        const turnArgs = resumedCodexThreadId
+            ? buildCodexResumeArgs(this.cmdArgs, resumedCodexThreadId, text)
+            : this.adapter.buildTurnArgs(this.cmdArgs, text);
+        const proc = spawn(this.cmdBin, turnArgs, {
             cwd: this.config.workDir,
             env: this.spawnEnv,
             stdio: ["ignore", "pipe", "pipe"],
@@ -541,6 +562,25 @@ export class HeadlessSession {
             // kill-tmux.
             if (this.proc !== proc)
                 return;
+            // A runner cannot know the Codex version before spawning it. An old binary reliably
+            // rejects the flag before it executes the prompt, so retrying only this precise failure
+            // is safe. Do NOT downgrade merely because a line failed JSON parsing: current Codex can
+            // interleave tool/MCP stderr with valid JSONL, and a second run could repeat real work.
+            if (!this.fellBackToRaw && code && !this.sawStructuredEvent && this.structuredOutputRejected) {
+                this.fellBackToRaw = true;
+                this.adapter = genericRawEngineAdapter;
+                this.mode = this.adapter.mode;
+                this.proc = null;
+                this.push(`[${this.config.clientType} CLI rejected --json; retrying this turn with raw output]`);
+                this.runOneShot(text);
+                return;
+            }
+            // A rejected/expired explicit ID is not retried as the same turn: the CLI may have started
+            // work before failing. Drop only that known-bad local key so the NEXT turn is safely fresh.
+            if (code && resumedCodexThreadId && this.codexThreadId === resumedCodexThreadId) {
+                this.codexThreadId = null;
+                writeState(this.config.statePath, this.config.id, null, "codex");
+            }
             // THE EXIT CODE STOPS BEING ONLY PROSE HERE (#545). Recorded after the staleness guard
             // on purpose: a turn aborted by its successor (see the kill above) must not overwrite
             // the report of the turn that replaced it — the loser's outcome is about a turn nobody
@@ -599,8 +639,12 @@ export class HeadlessSession {
             this.buf = this.buf.slice(nl + 1);
             if (!line)
                 continue;
-            if (this.mode === "stream-json")
-                this.handle(line);
+            if (this.mode === "stream-json") {
+                if (this.handle(line))
+                    this.sawStructuredEvent = true;
+                else if (this.adapter.rejectsStructuredOutput?.(line))
+                    this.structuredOutputRejected = true;
+            }
             else
                 this.pushRaw(line); // raw engine — the line IS the terminal output
         }
@@ -617,6 +661,10 @@ export class HeadlessSession {
             this.buf = "";
         }
     }
+    /** A stored id is used only for the supported structured `codex exec` shape. */
+    get codexResumeThreadId() {
+        return this.config.clientType === "codex" && this.mode === "stream-json" && isCodexThreadId(this.codexThreadId) ? this.codexThreadId : null;
+    }
     /** Raw-engine stdout: strip ANSI control codes and append to the transcript. */
     pushRaw(line) {
         const clean = stripAnsi(line);
@@ -630,12 +678,17 @@ export class HeadlessSession {
             this.transcript = this.transcript.slice(-3000);
     }
     handle(line) {
-        for (const ev of this.adapter.parseLine(line)) {
+        const events = this.adapter.parseLine(line);
+        for (const ev of events) {
             switch (ev.kind) {
                 case "session":
                     if (this.config.clientType === "claude") {
                         this.claudeSessionId = ev.sessionId;
-                        writeState(this.config.statePath, this.config.id, ev.sessionId);
+                        writeState(this.config.statePath, this.config.id, ev.sessionId, "claude");
+                    }
+                    else if (this.config.clientType === "codex" && isCodexThreadId(ev.sessionId)) {
+                        this.codexThreadId = ev.sessionId;
+                        writeState(this.config.statePath, this.config.id, ev.sessionId, "codex");
                     }
                     break;
                 case "assistant_text":
@@ -695,6 +748,7 @@ export class HeadlessSession {
         // character bound that matters is `MAX_PANE` in runtime.ts, applied on the way out.
         if (this.transcript.length > 4000)
             this.transcript = this.transcript.slice(-3000);
+        return events.length > 0;
     }
     push(line) {
         this.transcript.push(line);
@@ -842,36 +896,3 @@ export function parseCommand(command) {
     }
     return { bin: tokens[0] ?? "", args: tokens.slice(1) };
 }
-function loadFile(path) {
-    if (!path || !existsSync(path))
-        return {};
-    try {
-        return JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch {
-        return {};
-    }
-}
-function readState(path, id) {
-    return loadFile(path)[id] ?? null;
-}
-function writeState(path, id, claudeSessionId) {
-    if (!path)
-        return;
-    try {
-        const data = loadFile(path);
-        if (claudeSessionId)
-            data[id] = claudeSessionId;
-        else
-            delete data[id];
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, JSON.stringify(data));
-    }
-    catch {
-        /* best-effort persistence */
-    }
-}
-/** Default location for the resume-id store, under the repos base dir. */
-export function defaultStatePath(reposBaseDir) {
-    return join(reposBaseDir, "headless-sessions.json");
-}

package/dist/browser-runner/coding/repo-clone-job.js

@@ -0,0 +1,109 @@
+/**
+ * Cold-start clones as BACKGROUND jobs, over https or SSH (#858).
+ *
+ * #857's clone was one synchronous `git clone` inside a relay command: a repository that took longer
+ * than the relay's two-minute ceiling failed the call while git kept going, and `execFileSync` held the
+ * runner's event loop — its relay socket included — for as long as git ran. Here the clone is a job:
+ * started, answered at once, and run with an async `git` so the runner keeps serving everything else.
+ * The cloud reads the job back until it is `done` or `failed`; one job per folder, so asking again
+ * joins the clone in flight instead of starting a second one.
+ *
+ * Which URL: the machine's own credentials decide. https first (its credential helper — what
+ * `gh auth login` configures). If that is refused and the machine holds an SSH identity for github.com,
+ * `git@github.com:<owner>/<repo>.git` next — a machine that reaches GitHub only through a key used to
+ * fail a private repository with "could not read Username". `protocol` pins one or the other.
+ *
+ * The folder guards are {@link ensureRepo}'s owner-folder rules: an absent or empty folder is cloned
+ * into, a folder with anything in it never is, an empty folder inside another checkout is refused.
+ */
+import { execFile } from "node:child_process";
+import { rmSync } from "node:fs";
+import { promisify } from "node:util";
+import { checkWorkdir, probeGitSshIdentity } from "./repo.js";
+const run = promisify(execFile);
+export const cloneUrlFor = (slug, via) => (via === "ssh" ? `git@github.com:${slug}.git` : `https://github.com/${slug}.git`);
+/**
+ * Run a job to its end. Never rejects: every outcome is written onto `job`.
+ *
+ * `auto` tries https, then SSH only when https was refused AND the machine has an SSH identity — the
+ * probe runs only then, because it is a network round trip a clone that already worked does not need.
+ */
+export async function runCloneJob(job, protocol, deps) {
+    const order = protocol === "ssh" ? ["ssh"] : protocol === "https" ? ["https"] : ["https", "ssh"];
+    for (const via of order) {
+        if (via === "ssh" && protocol === "auto") {
+            const identity = deps.sshIdentity();
+            if (!identity) {
+                job.attempts.push("ssh: not tried — this machine has no SSH key that github.com accepts");
+                break;
+            }
+        }
+        try {
+            await deps.clone(job.path, cloneUrlFor(job.slug, via));
+            return Object.assign(job, { state: "done", via, finishedAt: deps.now() });
+        }
+        catch (e) {
+            job.attempts.push(`${via}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return Object.assign(job, {
+        state: "failed",
+        finishedAt: deps.now(),
+        error: `${job.attempts.join(" | ")} — the machine clones with its OWN git credentials: sign in over https there (\`gh auth login\`), or add an SSH key that github.com accepts.`,
+    });
+}
+/**
+ * Clone `url` into the owner's folder `dir` — async, never prompting, with the owner-folder guards.
+ * Rejects with git's reason (scrubbed of nothing: these URLs carry no token).
+ */
+export async function cloneIntoOwnFolder(dir, url) {
+    const at = checkWorkdir(dir);
+    if (at.exists && at.isDirectory && at.entryCount > 0)
+        throw new Error(`"${dir}" is not empty — never cloned into`);
+    if (at.exists && !at.isDirectory)
+        throw new Error(`"${dir}" is a file, not a folder`);
+    if (at.exists && at.insideWorkTree)
+        throw new Error(`"${dir}" is an empty folder inside another git checkout — not cloning a second repository into it`);
+    if (at.exists)
+        rmSync(dir, { recursive: true, force: true });
+    try {
+        await run("git", ["clone", url, dir], {
+            timeout: 60 * 60_000,
+            // No prompt, ever: a refusal must fail with git's reason, not wait on input nobody will give.
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_SSH_COMMAND: "ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new" },
+        });
+    }
+    catch (e) {
+        const stderr = String(e.stderr ?? "").trim() || (e instanceof Error ? e.message : "git clone failed");
+        throw new Error(stderr.slice(0, 300));
+    }
+}
+/** The production deps: real git, the real SSH probe. */
+export const liveCloneDeps = {
+    clone: cloneIntoOwnFolder,
+    sshIdentity: () => probeGitSshIdentity("github.com").identity,
+    now: () => Date.now(),
+};
+/**
+ * The runner's clone jobs, one per folder. `start` joins a clone in flight rather than starting a
+ * second; a finished or failed job is replaced by a new start, which is how a failed clone is retried.
+ */
+export class CloneJobs {
+    deps;
+    jobs = new Map();
+    constructor(deps = liveCloneDeps) {
+        this.deps = deps;
+    }
+    start(path, slug, protocol = "auto") {
+        const current = this.jobs.get(path);
+        if (current?.state === "cloning")
+            return current;
+        const job = { path, slug, state: "cloning", attempts: [], startedAt: this.deps.now() };
+        this.jobs.set(path, job);
+        void runCloneJob(job, protocol, this.deps);
+        return job;
+    }
+    status(path) {
+        return this.jobs.get(path) ?? { path, state: "none" };
+    }
+}

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

@@ -115,6 +115,23 @@ export function probeGitSshIdentity(host) {
     const isDeployKey = identity === null ? null : identity.includes("/");
     return { checked: true, host, identity, isDeployKey, raw };
 }
+/**
+ * Clone `cloneUrl` into the owner's folder `dir` — only when there is nothing there yet (#857).
+ *
+ * The cold-start step `coding_repo_add … clone:true` asks for. It is {@link ensureRepo}'s owner-folder
+ * clone and inherits every one of its guards: an existing checkout is left untouched, a folder with
+ * anything in it is never cloned into, an empty folder inside another checkout is refused, and the
+ * clone is a full one whose `origin` is the plain URL. Authentication is the MACHINE's own — its git
+ * credential helper for https — and a repository it cannot read fails with git's reason.
+ *
+ * `cloned` says whether this call cloned; false means the folder was already there and was not touched.
+ */
+export function cloneIntoWorkdir(dir, cloneUrl) {
+    const before = checkWorkdir(dir);
+    const empty = !before.exists || (before.isDirectory && before.entryCount === 0);
+    ensureRepo(dir, { cloneUrl, ownFolder: true });
+    return { cloned: empty, path: dir };
+}
 /**
  * Ensure a repo is present at `dir`, cloning it from `cloneUrl` if not. Idempotent
  * — an existing checkout is left alone (no clobber). For private repos the cloud
@@ -126,6 +143,14 @@ export function probeGitSshIdentity(host) {
  * `x-access-token` — the value this function used to hardcode — so an older cloud that
  * sends only `token` behaves exactly as before.
  *
+ * `ownFolder` marks a path the OWNER configured (a local checkout) rather than a managed dir
+ * (#828). Such a path is cloned into only when there is nothing there yet — absent, or an empty
+ * folder that is not inside another checkout — which is the normal state of an unpinned
+ * instance landing on a machine that has never cloned this repo. A folder with anything in it
+ * is run in exactly as it is, the behaviour a local path always had. The clone is a full one
+ * (the owner's own checkout must be able to rebase and read history), and its `origin` is left
+ * without the short-lived token, which would otherwise break every later push once it expired.
+ *
  * Returns the absolute working directory. Throws on clone failure so the caller
  * can surface it (a session can't start without its repo).
  */
@@ -147,15 +172,36 @@ export function ensureRepo(dir, opts = {}) {
     if (existsSync(dir)) {
         const entries = readdirSync(dir);
         if (entries.length > 0) {
+            // The owner's own folder (a monorepo subfolder, a plain project) — run in it untouched.
+            if (opts.ownFolder)
+                return dir;
             throw new Error(`Refusing to clone into non-empty directory "${dir}" (no .git found) — move it aside or point at an empty path.`);
         }
+        if (opts.ownFolder && checkWorkdir(dir).insideWorkTree) {
+            throw new Error(`"${dir}" is an empty folder inside another git checkout — not cloning a second repository into it. Point this repo at the checkout itself, or remove the folder.`);
+        }
         rmSync(dir, { recursive: true, force: true });
     }
     const url = authenticatedCloneUrl(opts.cloneUrl, opts.token, opts.tokenUsername);
-    const args = ["clone", "--depth", "1"];
+    const args = ["clone"];
+    if (!opts.ownFolder)
+        args.push("--depth", "1");
     if (opts.branch)
         args.push("--branch", opts.branch);
     args.push(url, dir);
-    execFileSync("git", args, { stdio: "pipe", timeout: 180_000 });
+    try {
+        // No prompt, ever (#857): a clone the machine's credentials cannot authorise must FAIL, with git's
+        // own reason, rather than wait on a username prompt no one will ever see until the timeout.
+        execFileSync("git", args, { stdio: "pipe", timeout: 180_000, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+        if (opts.ownFolder && url !== opts.cloneUrl)
+            execFileSync("git", ["remote", "set-url", "origin", opts.cloneUrl], { cwd: dir, stdio: "pipe" });
+    }
+    catch (e) {
+        // `e.message` carries the whole command line, token included — the reason git's own
+        // stderr is used instead, and the token scrubbed from that too in case git echoed the URL.
+        const stderr = String(e.stderr ?? "").trim() || "git clone failed";
+        const why = opts.token ? stderr.split(opts.token).join("***") : stderr;
+        throw new Error(`Could not clone ${opts.cloneUrl} into "${dir}": ${why.slice(0, 400)}`);
+    }
     return dir;
 }

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

@@ -4,13 +4,16 @@ import { RunnerInputError } from "../errors.js";
 import { defaultStatePath, HeadlessSession } from "./headless.js";
 import { InspectError, readGitRemoteOrigin, readRepoFile, repoSearch, repoSync, repoTree, runRepoGit } from "./inspect.js";
 import { fastForwardRepo, switchRepoBranch } from "./repo-write.js";
-import { checkWorkdir, ensureRepo, sanitizeSessionName } from "./repo.js";
+import { checkWorkdir, cloneIntoWorkdir, ensureRepo, sanitizeSessionName } from "./repo.js";
+import { CloneJobs } from "./repo-clone-job.js";
 import { asTurnAuthor } from "./turn-author.js";
 /** Hard cap on a pane returned to the brain/console (matches the worker MAX_PANE_CHARS). */
 const MAX_PANE = 64 * 1024;
 export class CodingRuntime {
     reposBaseDir;
     sessions = new Map();
+    /** Background cold-start clones, one per folder (#858). */
+    cloneJobs = new CloneJobs();
     /**
      * Active human handoffs keyed by session id. `resolved` flips when the human
      * finishes (console "Resume" / submits a value); the brain workflow polls
@@ -111,6 +114,28 @@ export class CodingRuntime {
     checkRepo(input) {
         return checkWorkdir(this.resolveWorkDir(input));
     }
+    /**
+     * Start — or join — a background clone of GitHub `slug` into an absent or empty owner folder (#858).
+     * Answers at once with the job; `cloneStatus` reads it back. See `repo-clone-job.ts`.
+     */
+    startClone(input) {
+        if (!input.workDir || !input.slug || !/^[\w.-]+\/[\w.-]+$/.test(input.slug))
+            throw new InspectError("workDir and an owner/repo slug are required");
+        const protocol = input.protocol === "https" || input.protocol === "ssh" ? input.protocol : "auto";
+        return this.cloneJobs.start(this.resolveWorkDir({ workDir: input.workDir }), input.slug, protocol);
+    }
+    /** The background clone for this folder, or `state: "none"` (#858). */
+    cloneStatus(input) {
+        if (!input.workDir)
+            throw new InspectError("workDir is required");
+        return this.cloneJobs.status(this.resolveWorkDir({ workDir: input.workDir }));
+    }
+    /** Clone a repository into an absent or empty owner folder (#857) — see `cloneIntoWorkdir`. */
+    cloneRepo(input) {
+        if (!input.workDir || !input.cloneUrl)
+            throw new InspectError("workDir and cloneUrl are required");
+        return cloneIntoWorkdir(this.resolveWorkDir({ workDir: input.workDir }), input.cloneUrl);
+    }
     static taskTypes() {
         return ["coding.session"];
     }
@@ -121,10 +146,11 @@ export class CodingRuntime {
             // Resolve the working dir and ensure the repo is present (clone on first
             // start). A user-supplied local path may use ~ — expand it; otherwise
             // clone into a managed dir. Without this the CLI would launch nowhere.
+            // A local path is cloned into only when absent or empty (#828).
             const workDir = input.workDir
                 ? resolve(input.workDir.replace(/^~(?=$|\/)/, homedir()))
                 : join(this.reposBaseDir, sanitizeSessionName(input.repoId));
-            ensureRepo(workDir, { cloneUrl: input.cloneUrl, branch: input.branch, token: input.token, tokenUsername: input.tokenUsername });
+            ensureRepo(workDir, { cloneUrl: input.cloneUrl ?? input.emptyCheckoutCloneUrl, branch: input.branch, token: input.token, tokenUsername: input.tokenUsername, ownFolder: Boolean(input.workDir) });
             session = new HeadlessSession({
                 id: input.sessionId,
                 workDir,
@@ -254,6 +280,8 @@ export class CodingRuntime {
             sessionId,
             alive: s.alive,
             engineLabel: s.engineLabel,
+            // Whether an engine is mid-turn — what `runner_update` waits on before restarting (#859).
+            runState: s.runState(),
         }));
     }
     /** Rich diagnostics for every tracked session — the console's transparency view. */

package/dist/browser-runner/runner.js

@@ -94,7 +94,7 @@ export class LocalRunner {
             runtimePlane: "pags",
             runnerRole: "tool-executor",
             capabilities: [...CAPABILITIES, ...CodingRuntime.capabilities()],
-            taskTypes: ["echo", "browser.open", "job.apply_agent", ...CodingRuntime.taskTypes()],
+            taskTypes: ["echo", "browser.open", "job.apply_agent", "site_builder_runtime", ...CodingRuntime.taskTypes()],
             approvalRequiredFor: [...APPROVAL_REQUIRED_TASKS],
         };
     }
@@ -187,6 +187,39 @@ export class LocalRunner {
         void this.endTakeover(id).catch(() => undefined);
         return task;
     }
+    /**
+     * Receive a bounded FWS capture manifest from the PAGS broker. The pixels remain behind the
+     * job-scoped signed URLs; keeping the manifest on the durable local task lets Claude/Codex
+     * inspect both layouts after a relay reconnect without ever receiving FWS OAuth material.
+     */
+    appendCaptureArtifacts(id, artifacts) {
+        const task = this.requireTask(id);
+        if (task.type !== "site_builder_runtime")
+            throw new RunnerInputError("Capture artifacts are only valid for Website Builder tasks");
+        if (!Array.isArray(artifacts) || artifacts.length < 1 || artifacts.length > 2)
+            throw new RunnerInputError("Expected one or two capture artifacts");
+        const valid = artifacts.map((item) => {
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                throw new RunnerInputError("Invalid capture artifact");
+            const a = item;
+            if (typeof a.id !== "string" || !/^[a-f0-9]{64}$/.test(a.id) || (a.device !== "desktop" && a.device !== "mobile") ||
+                typeof a.contentType !== "string" || typeof a.bytes !== "number" || !Number.isInteger(a.bytes) || a.bytes <= 0 || a.bytes > 4 * 1024 * 1024 ||
+                typeof a.url !== "string" || a.url.length > 4_000 || !a.url.startsWith("https://api.proagentstore.online/")) {
+                throw new RunnerInputError("Invalid capture artifact");
+            }
+            return a;
+        });
+        const prior = Array.isArray(task.input.captureArtifacts) ? task.input.captureArtifacts.filter((item) => !!item && typeof item === "object" && !Array.isArray(item)) : [];
+        const merged = new Map();
+        for (const artifact of [...prior, ...valid])
+            if (typeof artifact.id === "string")
+                merged.set(artifact.id, artifact);
+        task.input = { ...task.input, captureArtifacts: [...merged.values()].slice(-8) };
+        task.updatedAt = new Date().toISOString();
+        this.store.putTask(task);
+        this.addTaskEvent(task, "site_builder.capture_received", `FWS ${valid.map((artifact) => artifact.device).join(" + ")} capture received`, { artifacts: valid.map(({ id, device, contentType, bytes }) => ({ id, device, contentType, bytes })) });
+        return task;
+    }
     /**
      * Tear everything down, and never let one failure strand the rest (#274).
      *

package/dist/browser-runner/server.js

@@ -82,6 +82,11 @@ async function route(runner, req, res) {
     if (req.method === "POST" && cancelMatch) {
         return json(res, 200, runner.cancelTask(cancelMatch[1]));
     }
+    const artifactMatch = path.match(/^\/tasks\/([^/]+)\/artifacts$/);
+    if (req.method === "POST" && artifactMatch) {
+        const body = await readJson(req);
+        return json(res, 200, runner.appendCaptureArtifacts(artifactMatch[1], body.captureArtifacts ?? []));
+    }
     if (req.method === "GET" && path === "/events") {
         const limit = clampLimit(url.searchParams.get("limit"), 100, 500);
         return json(res, 200, { events: runner.store.listEvents(limit) });
@@ -378,6 +383,28 @@ async function route(runner, req, res) {
             return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
         }
     }
+    // Background cold-start clones (#858): start (or join) one, and read it back. An older runner 404s
+    // both, and the cloud falls back to the synchronous `/coding/clone` below.
+    if (req.method === "POST" && (path === "/coding/clone-start" || path === "/coding/clone-status")) {
+        const b = await readJson(req);
+        try {
+            return json(res, 200, path === "/coding/clone-start" ? runner.coding.startClone(b) : runner.coding.cloneStatus(b));
+        }
+        catch (e) {
+            return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    // Clone into an absent or empty owner folder (#857) — the cold-start half of `coding_repo_add`.
+    // An older runner 404s this, and the cloud says the CLI must be updated rather than guessing.
+    if (req.method === "POST" && path === "/coding/clone") {
+        const b = await readJson(req);
+        try {
+            return json(res, 200, runner.coding.cloneRepo(b));
+        }
+        catch (e) {
+            return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
     if (req.method === "POST" && path === "/coding/tree") {
         const b = await readJson(req);
         try {

package/dist/browser-runner/task-types.js

@@ -17,4 +17,6 @@ export const WORKFLOW_DRIVEN_TASKS = new Set([
     "job.apply_agent",
     "browser.task",
     "browser.handoff",
+    // #841: local Claude/Codex authors an FWS draft; PAGS retains the audit and deployment gate.
+    "site_builder_runtime",
 ]);

package/dist/chunk-JOWYSZOL.js

@@ -0,0 +1,97 @@
+// src/bootstrap/payload.ts
+import { execFile } from "child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { promisify } from "util";
+var run = promisify(execFile);
+var CLI_PACKAGE = "@proagentstore/cli";
+var BOOTSTRAP_ENV = "PAGS_BOOTSTRAP";
+var NO_SELF_UPDATE_ENV = "PAGS_NO_SELF_UPDATE";
+var KEEP = 2;
+function payloadRoot() {
+  return process.env.PAGS_CLI_CACHE || join(homedir(), ".config", "proagentstore", "cli");
+}
+function olderThan(a, b) {
+  const parse = (v) => /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim())?.slice(1).map(Number);
+  const x = parse(a);
+  const y = parse(b);
+  if (!x || !y) return false;
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i];
+  return false;
+}
+function payloadAt(dir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+    if (pkg.name !== CLI_PACKAGE || !pkg.version) return null;
+    const entry = join(dir, pkg.pagsPayload || "dist/index.js");
+    return existsSync(entry) ? { version: pkg.version, entry } : null;
+  } catch {
+    return null;
+  }
+}
+var installedAt = (prefix) => join(prefix, "node_modules", ...CLI_PACKAGE.split("/"));
+var packageDir = (root, version) => installedAt(join(root, version));
+function cachedPayloads(root = payloadRoot()) {
+  let names;
+  try {
+    names = readdirSync(root);
+  } catch {
+    return [];
+  }
+  return names.flatMap((v) => v.startsWith(".") ? [] : payloadAt(packageDir(root, v)) ?? []);
+}
+function newestPayload(payloads) {
+  return payloads.reduce((best, p) => !best || olderThan(best.version, p.version) ? p : best, null);
+}
+async function latestPublishedVersion(timeoutMs = 3e4) {
+  try {
+    const { stdout } = await run("npm", ["view", CLI_PACKAGE, "version"], { timeout: timeoutMs });
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+async function npmInstallInto(dir, version) {
+  try {
+    await run("npm", ["install", "--prefix", dir, "--omit=dev", "--no-audit", "--no-fund", "--no-save", `${CLI_PACKAGE}@${version}`], { timeout: 5 * 6e4 });
+  } catch (e) {
+    const stderr = String(e.stderr ?? "").trim();
+    throw new Error((stderr || (e instanceof Error ? e.message : String(e))).slice(-400));
+  }
+}
+async function installPayload(version, root = payloadRoot(), install = npmInstallInto) {
+  const done = payloadAt(packageDir(root, version));
+  if (done) return done;
+  mkdirSync(root, { recursive: true });
+  const scratch = mkdtempSync(join(root, `.install-${version}-`));
+  try {
+    await install(scratch, version);
+    if (payloadAt(installedAt(scratch))?.version !== version) throw new Error(`npm installed no ${CLI_PACKAGE}@${version}`);
+    try {
+      renameSync(scratch, join(root, version));
+    } catch (e) {
+      if (!payloadAt(packageDir(root, version))) throw e;
+    }
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+  const payload = payloadAt(packageDir(root, version));
+  if (!payload) throw new Error(`${CLI_PACKAGE}@${version} is not usable after install`);
+  for (const old of cachedPayloads(root).sort((a, b) => olderThan(a.version, b.version) ? 1 : -1).slice(KEEP)) {
+    rmSync(join(root, old.version), { recursive: true, force: true });
+  }
+  return payload;
+}
+
+export {
+  CLI_PACKAGE,
+  BOOTSTRAP_ENV,
+  NO_SELF_UPDATE_ENV,
+  olderThan,
+  payloadAt,
+  cachedPayloads,
+  newestPayload,
+  latestPublishedVersion,
+  installPayload
+};

package/dist/index.js

@@ -1,4 +1,11 @@
 #!/usr/bin/env node
+import {
+  BOOTSTRAP_ENV,
+  CLI_PACKAGE,
+  installPayload,
+  latestPublishedVersion,
+  olderThan
+} from "./chunk-JOWYSZOL.js";
 
 // src/index.ts
 import { createRequire as createRequire3 } from "module";
@@ -1140,6 +1147,9 @@ function findWorkspaceRoot() {
   }
   return process.cwd();
 }
+function runsFromSource() {
+  return existsSync6(resolve4(findWorkspaceRoot(), "packages", "browser-runner", "src", "index.ts"));
+}
 function bundledRunnerPath() {
   return fileURLToPath2(new URL("./browser-runner/index.js", import.meta.url));
 }
@@ -1194,6 +1204,40 @@ async function waitForLocalRunner(opts, timeoutMs = 15e3) {
 // src/commands/runner/relay.ts
 import { hostname as hostname3 } from "os";
 
+// src/commands/runner/self-update.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var run = promisify(execFile);
+var RUNNER_UPDATE_PATH = "/pags/runner/update";
+var RUNNER_RESTART_EXIT_CODE = 75;
+var SUPERVISED_ENV = "PAGS_UP_SUPERVISED";
+function planRunnerUpdate(f) {
+  if (f.fromSource) return { action: "refused", current: f.current, reason: "This runner runs from a source checkout \u2014 update it with `git pull` there, not npm." };
+  if (!f.latest) return { action: "refused", current: f.current, reason: `npm could not be asked for the latest ${CLI_PACKAGE} from this machine.` };
+  if (!olderThan(f.current, f.latest)) return { action: "up-to-date", current: f.current };
+  if (!f.supervised) {
+    return {
+      action: "refused",
+      current: f.current,
+      reason: `This runner was not started by a \`pags up\` that can restart it (\`pags runner connect\` directly, or a \`pags up\` older than the respawn). Update once at the machine: \`npm i -g ${CLI_PACKAGE}\` and restart \`pags up\` \u2014 later updates can then be done remotely.`
+    };
+  }
+  if (f.busy.length > 0) return { action: "wait", current: f.current, latest: f.latest, waitingFor: f.busy };
+  return { action: "update", current: f.current, latest: f.latest };
+}
+async function installVersion(version2) {
+  if (process.env[BOOTSTRAP_ENV]) {
+    await installPayload(version2);
+    return;
+  }
+  try {
+    await run("npm", ["i", "-g", `${CLI_PACKAGE}@${version2}`], { timeout: 5 * 6e4 });
+  } catch (e) {
+    const stderr = String(e.stderr ?? "").trim();
+    throw new Error((stderr || (e instanceof Error ? e.message : String(e))).slice(-400));
+  }
+}
+
 // src/commands/runner/membership.ts
 function isEligible(inst, thisNode, alsoKnownAs = []) {
   if (inst.status !== "active") return false;
@@ -1236,6 +1280,20 @@ function instanceLabel(inst) {
   const short = `${inst.id.slice(0, 8)}\u2026`;
   return inst.name ? `${inst.name} (${short})` : short;
 }
+function reattachPlan(request, state) {
+  const target = typeof request?.attach === "string" && request.attach ? request.attach : null;
+  const force = target !== null && request?.force === true;
+  if (!state.watching && !(target && state.scope.includes(target))) {
+    return {
+      target,
+      unblock: false,
+      detach: false,
+      force: false,
+      refuse: "This machine's `pags up` was started with --instance, so it serves only that agent. Restart it without --instance to let it take repinned agents."
+    };
+  }
+  return { target, unblock: target !== null && state.blocked, detach: target !== null && state.held, force };
+}
 
 // src/commands/runner/status-line.ts
 var STATUS_PREFIX = "PAGS-STATUS";
@@ -1268,6 +1326,8 @@ function parseStatusLine(line) {
 }
 
 // src/commands/runner/relay.ts
+var MEMBERSHIP_SYNC_PATH = "/pags/membership/sync";
+var CLI_CONTROL_PATHS = /* @__PURE__ */ new Set([MEMBERSHIP_SYNC_PATH, RUNNER_UPDATE_PATH]);
 async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force = false, watchInstances = false) {
   const apiBase = pagsApiBase(opts.apiBase).replace(/^http/, "ws");
   const pagsToken = clean(opts.pagsToken) || clean(process.env.PAGS_TOKEN) || clean(loadSession()?.token);
@@ -1303,11 +1363,86 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
   };
   const attached = /* @__PURE__ */ new Map();
   const blocked = /* @__PURE__ */ new Set();
+  let syncing = Promise.resolve();
+  const forceNext = /* @__PURE__ */ new Set();
   const reportRegistration = () => {
     const { agents, state } = registrationStatus(attached.keys(), registered);
     writeLine(formatStatusLine({ registration: state, agents, reason: state === "ok" ? void 0 : lastRegisterError }));
   };
   for (const id of instanceIds) await registerRuntime(id);
+  const updateFacts = async () => {
+    const sessions = await requestRunner("GET", "/coding/sessions", {
+      url: localUrl,
+      token: runnerToken,
+      instanceId: instanceIds[0]
+    }).catch(() => ({ sessions: [] }));
+    return {
+      current: CLI_VERSION,
+      latest: await latestPublishedVersion(),
+      fromSource: runsFromSource(),
+      supervised: process.env[SUPERVISED_ENV] === "1",
+      busy: (sessions.sessions ?? []).filter((s) => s.alive && s.runState && s.runState !== "idle").map((s) => s.sessionId)
+    };
+  };
+  const installAndRestart = async (plan) => {
+    writeLine(`Updating ${plan.current} \u2192 ${plan.latest} (runner_update)\u2026`);
+    await installVersion(plan.latest);
+    writeLine(`Installed ${plan.latest} \u2014 restarting; every agent re-attaches on the way back up.`);
+    setTimeout(() => {
+      for (const id of [...attached.keys()]) detach(id);
+      process.exit(RUNNER_RESTART_EXIT_CODE);
+    }, 500).unref();
+  };
+  let updateWaiting = false;
+  const updateWhenIdle = () => {
+    if (updateWaiting) return;
+    updateWaiting = true;
+    const until = Date.now() + 60 * 6e4;
+    const tick = () => setTimeout(async () => {
+      const plan = planRunnerUpdate(await updateFacts());
+      if (plan.action === "update") {
+        await installAndRestart(plan).catch((e) => writeError(`runner_update: install failed \u2014 ${e instanceof Error ? e.message : String(e)}`));
+        updateWaiting = false;
+      } else if (plan.action === "wait" && Date.now() < until) tick();
+      else updateWaiting = false;
+    }, 15e3).unref();
+    tick();
+  };
+  const answerUpdate = async (body) => {
+    const dryRun = body?.dryRun === true;
+    const plan = planRunnerUpdate(await updateFacts());
+    if (dryRun || plan.action === "up-to-date" || plan.action === "refused") return { status: 200, result: { ...plan, dryRun } };
+    if (plan.action === "wait") {
+      updateWhenIdle();
+      return { status: 200, result: { ...plan, detail: "Restarts itself as soon as these engines finish their turns \u2014 no run is cut off." } };
+    }
+    try {
+      await installAndRestart(plan);
+    } catch (e) {
+      return { status: 500, result: { error: `npm could not install ${plan.latest}: ${e instanceof Error ? e.message : String(e)}` } };
+    }
+    return { status: 200, result: { action: "restarting", current: plan.current, latest: plan.latest } };
+  };
+  const answerControl = async (path, body) => {
+    if (path === RUNNER_UPDATE_PATH) return answerUpdate(body);
+    if (path !== MEMBERSHIP_SYNC_PATH) return { status: 404, result: { error: `Unknown runner control ${path}` } };
+    const request = body;
+    const named = typeof request?.attach === "string" ? request.attach : "";
+    const plan = reattachPlan(request, { held: attached.has(named), blocked: blocked.has(named), watching: watchInstances, scope: instanceIds });
+    if (plan.refuse) return { status: 409, result: { error: plan.refuse } };
+    if (plan.target) {
+      if (plan.unblock) blocked.delete(plan.target);
+      if (plan.detach) detach(plan.target);
+      if (plan.force) forceNext.add(plan.target);
+    }
+    if (watchInstances) await syncMembership();
+    else if (plan.target) {
+      await registerRuntime(plan.target);
+      attach(plan.target);
+    }
+    if (plan.target && !attached.has(plan.target)) forceNext.delete(plan.target);
+    return { status: 200, result: { attached: [...attached.keys()], ...plan.target ? { target: plan.target, holding: attached.has(plan.target) } : {} } };
+  };
   const attach = (id, label = `${id.slice(0, 8)}\u2026`) => {
     if (attached.has(id)) return;
     const mintToken = () => requestPags("POST", `/v1/relay/${apiPathSegment(id)}/token`, { ...opts, pagsToken }, {}).then((r) => r.token);
@@ -1319,7 +1454,8 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
         mintToken,
         localUrl,
         runnerToken,
-        force,
+        // `pags up --force` for the whole process, or for this one agent at the cloud's request (#856).
+        force || forceNext.delete(id),
         (conflicted) => {
           blocked.add(conflicted);
           attached.delete(conflicted);
@@ -1336,7 +1472,8 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
           if (!shouldRegisterOnOpen(reconnect, registered.has(openedId))) return;
           await registerRuntime(openedId, reconnect ? false : force);
           reportRegistration();
-        }
+        },
+        answerControl
       )
     );
     if (label) writeLine(`Attached agent: ${label}`);
@@ -1396,36 +1533,42 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
       writeLine(`Relay conflict cleared: ${id.slice(0, 8)}\u2026 \u2014 the other runner is gone; reattaching.`);
     }
   }
+  function syncMembership() {
+    syncing = syncing.catch(() => void 0).then(async () => {
+      await clearFinishedConflicts();
+      const res = await requestPags(
+        "GET",
+        "/v1/instances/my/instances",
+        { ...opts, pagsToken }
+      );
+      const { attach: toAttach, detach: toDetach } = diffMembership(
+        attached.keys(),
+        res.instances ?? [],
+        runnerNode,
+        blocked,
+        // The names this machine has also worn. Without them a pin made under a
+        // previous hostname reads as "pinned to another machine", and this poll
+        // detaches the agent twenty seconds after startup attached it (#379).
+        machine.names
+      );
+      for (const inst of toAttach) {
+        await registerRuntime(inst.id);
+        attach(inst.id, instanceLabel(inst));
+      }
+      for (const id of toDetach) detach(id);
+      const pending = pendingRegistrations(attached.keys(), registered);
+      if (pending.length) {
+        for (const id of pending) await registerRuntime(id);
+        reportRegistration();
+      }
+    });
+    return syncing;
+  }
   function startDiscovery() {
     const tick = () => {
       const timer = setTimeout(async () => {
         try {
-          await clearFinishedConflicts();
-          const res = await requestPags(
-            "GET",
-            "/v1/instances/my/instances",
-            { ...opts, pagsToken }
-          );
-          const { attach: toAttach, detach: toDetach } = diffMembership(
-            attached.keys(),
-            res.instances ?? [],
-            runnerNode,
-            blocked,
-            // The names this machine has also worn. Without them a pin made under a
-            // previous hostname reads as "pinned to another machine", and this poll
-            // detaches the agent twenty seconds after startup attached it (#379).
-            machine.names
-          );
-          for (const inst of toAttach) {
-            await registerRuntime(inst.id);
-            attach(inst.id, instanceLabel(inst));
-          }
-          for (const id of toDetach) detach(id);
-          const pending = pendingRegistrations(attached.keys(), registered);
-          if (pending.length) {
-            for (const id of pending) await registerRuntime(id);
-            reportRegistration();
-          }
+          await syncMembership();
         } catch {
         }
         tick();
@@ -1435,7 +1578,7 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
     tick();
   }
 }
-function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, force = false, onConflict, onOpen) {
+function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, force = false, onConflict, onOpen, onControl) {
   let backoffMs = 1e3;
   let reconnecting = false;
   let closed = false;
@@ -1489,6 +1632,14 @@ function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, f
         return;
       }
       if (!cmd.id || !cmd.path) return;
+      if (onControl && CLI_CONTROL_PATHS.has(cmd.path)) {
+        const reply = await onControl(cmd.path, cmd.body).catch((err) => ({ status: 500, result: { error: err instanceof Error ? err.message : String(err) } }));
+        try {
+          ws.send(JSON.stringify({ id: cmd.id, ...reply }));
+        } catch {
+        }
+        return;
+      }
       const method = (cmd.method || "POST").toUpperCase();
       const hasBody = method !== "GET" && method !== "HEAD" && cmd.body !== void 0;
       try {
@@ -1594,6 +1745,7 @@ function createRunnerCommand() {
       shuttingDown = true;
       if (!runner.killed) runner.kill("SIGTERM");
     };
+    process.once("exit", shutdown);
     process.once("SIGINT", () => {
       shutdown();
       process.exit(0);
@@ -1952,10 +2104,11 @@ var upCommand = new Command8("up").description("Start the browser runner for all
   if (opts.headless) args.push("--headless");
   if (opts.force) args.push("--force");
   if (!opts.instance) args.push("--watch-instances");
-  const child = spawn4(process.execPath, args, {
+  const spawnChild = () => spawn4(process.execPath, args, {
     stdio: ["ignore", "pipe", "pipe"],
-    env: { ...process.env, PAGS_TOKEN: session.token }
+    env: { ...process.env, PAGS_TOKEN: session.token, [SUPERVISED_ENV]: "1" }
   });
+  let child = spawnChild();
   const logs = [];
   const handleOutput = (data2) => {
     const text = data2.toString("utf-8");
@@ -2013,10 +2166,20 @@ var upCommand = new Command8("up").description("Start the browser runner for all
       }
     }
   };
-  child.stdout?.on("data", handleOutput);
-  child.stderr?.on("data", handleOutput);
   let childDead = false;
-  child.on("exit", (code) => {
+  const wire = () => {
+    child.stdout?.on("data", handleOutput);
+    child.stderr?.on("data", handleOutput);
+    child.on("exit", onChildExit);
+  };
+  function onChildExit(code) {
+    if (code === RUNNER_RESTART_EXIT_CODE) {
+      state.lastEvent = "Runner updated remotely \u2014 restarting on the new version";
+      printStatus(state);
+      child = spawnChild();
+      wire();
+      return;
+    }
     childDead = true;
     if (code && code !== 0) {
       state.runner = "error";
@@ -2025,7 +2188,8 @@ var upCommand = new Command8("up").description("Start the browser runner for all
       if (recent.length) state.lastEvent += ": " + recent[recent.length - 1].slice(0, 60);
       printStatus(state);
     }
-  });
+  }
+  wire();
   const shutdown = () => {
     child.kill();
     clearScreen();

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@proagentstore/cli",
-  "version": "0.4.61",
+  "version": "0.4.63",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "pags": "dist/index.js"
+    "pags": "dist/bootstrap.js"
   },
+  "pagsPayload": "dist/index.js",
   "homepage": "https://github.com/ProAgentStore/platform#readme",
   "repository": {
     "type": "git",
@@ -25,7 +26,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "pnpm --filter @proagentstore/browser-runner build && tsup src/index.ts --format esm --dts && node scripts/copy-browser-runner.mjs",
+    "build": "pnpm --filter @proagentstore/browser-runner build && tsup src/index.ts src/bootstrap.ts --format esm --dts && node scripts/copy-browser-runner.mjs",
     "dev": "tsx src/index.ts",
     "typecheck": "tsc --noEmit"
   },