@proagentstore/cli 0.4.90 → 0.4.92

package/dist/index.js

@@ -1406,6 +1406,462 @@ function parseStatusLine(line) {
   return status;
 }
 
+// src/commands/runner/auto-update.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync6, readFileSync as readFileSync7, renameSync as renameSync2, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname3, join as join8 } from "path";
+
+// 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/auto-update.ts
+function autoUpdateStatusWire(status) {
+  if (!status) return void 0;
+  return {
+    "waiting-for-idle": "waiting_for_idle",
+    running: "installing",
+    "verified-success": "verified_success",
+    failure: "failed"
+  }[status] ?? status;
+}
+var statuses = /* @__PURE__ */ new Set([
+  "enabled",
+  "checking",
+  "waiting-for-idle",
+  "running",
+  "restarting",
+  "verified-success",
+  "offline",
+  "unsupported",
+  "failure"
+]);
+function parseStatus(value) {
+  if (typeof value !== "string") return void 0;
+  const readable = {
+    waiting_for_idle: "waiting-for-idle",
+    installing: "running",
+    verified_success: "verified-success",
+    failed: "failure"
+  }[value] ?? value;
+  return statuses.has(readable) ? readable : void 0;
+}
+function autoUpdatePolicyKey(machineId, env = process.env) {
+  return `${env.PAGS_LOCK_ACCOUNT?.trim() || "default"}:${machineId.trim() || "unidentified"}`;
+}
+function autoUpdatePolicyPath(env = process.env) {
+  return env.PAGS_AUTO_UPDATE_POLICY_FILE?.trim() || join8(configDir(env), "auto-update.json");
+}
+function parseAutoUpdatePolicy(value) {
+  if (!value || typeof value !== "object") return null;
+  const raw = value;
+  const autoUpdate = raw.autoUpdate ?? raw.auto_update;
+  if (typeof autoUpdate !== "boolean") return null;
+  const status = parseStatus(raw.status ?? raw.autoUpdateStatus ?? raw.auto_update_status);
+  const latestVersion = raw.latestVersion ?? raw.latest_version;
+  const lastAttemptAt = raw.lastAttemptAt ?? raw.last_attempt_at;
+  const reason = raw.reason;
+  return {
+    autoUpdate,
+    ...status ? { status } : {},
+    ...typeof latestVersion === "string" ? { latestVersion } : {},
+    ...typeof lastAttemptAt === "string" ? { lastAttemptAt } : {},
+    ...typeof reason === "string" ? { reason } : {}
+  };
+}
+function policyFromResponse(value) {
+  if (!value || typeof value !== "object") return null;
+  const raw = value;
+  const direct = raw.autoUpdatePolicy ?? raw.auto_update_policy ?? raw.policy;
+  if (typeof direct === "boolean") {
+    return parseAutoUpdatePolicy({
+      autoUpdate: direct,
+      status: raw.autoUpdateStatus ?? raw.auto_update_status,
+      latestVersion: raw.latestVersion ?? raw.latest_version,
+      lastAttemptAt: raw.lastAttemptAt ?? raw.last_attempt_at,
+      reason: raw.reason
+    });
+  }
+  return parseAutoUpdatePolicy(direct) ?? parseAutoUpdatePolicy(raw.machine && typeof raw.machine === "object" ? raw.machine.autoUpdatePolicy ?? raw.machine.auto_update_policy : void 0);
+}
+function loadAutoUpdatePolicy(key, env = process.env) {
+  try {
+    const data = JSON.parse(readFileSync7(autoUpdatePolicyPath(env), "utf8"));
+    if (data.v !== 1 || !data.policies || typeof data.policies !== "object") return null;
+    return parseAutoUpdatePolicy(data.policies[key]);
+  } catch {
+    return null;
+  }
+}
+function saveAutoUpdatePolicy(key, policy, env = process.env) {
+  const path = autoUpdatePolicyPath(env);
+  try {
+    let old = { v: 1, policies: {} };
+    if (existsSync7(path)) {
+      const parsed = JSON.parse(readFileSync7(path, "utf8"));
+      if (parsed.v === 1 && parsed.policies && typeof parsed.policies === "object") old = parsed;
+    }
+    mkdirSync6(dirname3(path), { recursive: true });
+    const next = { v: 1, policies: { ...old.policies, [key]: policy } };
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync5(temp, JSON.stringify(next, null, 2), { mode: 384 });
+    renameSync2(temp, path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function nextAutoUpdateDelayMs(failures, random = Math.random) {
+  const base = failures > 0 ? Math.min(60 * 6e4, 6e4 * 2 ** Math.min(failures - 1, 6)) : 6 * 60 * 6e4;
+  const jitter = 0.85 + Math.max(0, Math.min(1, random())) * 0.3;
+  return Math.round(base * jitter);
+}
+function policyScheduleAction(previous, next, wasAuthoritative) {
+  if (!next.autoUpdate) return "cancel";
+  if (!wasAuthoritative || !previous.autoUpdate) return "start";
+  return "keep";
+}
+function mayAutomaticallyRestart(input) {
+  return input.authoritative && input.enabled && input.workObserved && input.busy.length === 0;
+}
+
+// src/commands/runner/auto-update-controller.ts
+var AutomaticUpdateController = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    this.clearTimer = deps.clearTimer ?? ((timer) => clearTimeout(timer));
+  }
+  deps;
+  timer = null;
+  checking = false;
+  waiting = false;
+  installing = false;
+  failures = 0;
+  setTimer;
+  clearTimer;
+  /** Called only for a true policy transition. `keep` deliberately leaves a due heartbeat timer alone. */
+  onPolicy(action) {
+    if (action === "cancel") return this.cancel();
+    if (action === "start") this.schedule(true);
+  }
+  /** Testable immediate entry point; production reaches it through the scheduled timer. */
+  async runNow() {
+    const current = this.deps.policy();
+    if (this.checking || this.waiting || !current.authoritative || !current.value.autoUpdate) return;
+    this.checking = true;
+    try {
+      if (!await this.deps.refreshPolicy() || !this.enabled()) {
+        this.deps.status("offline", { reason: "The owner policy could not be refreshed; automatic update is deferred." });
+        return;
+      }
+      await this.decide(false);
+    } catch (error) {
+      this.fail(error);
+    } finally {
+      this.checking = false;
+    }
+  }
+  /** Explicit remote updates and unattended checks share this single flight. */
+  async installManually(plan) {
+    return this.install(plan, false);
+  }
+  enabled() {
+    const { value, authoritative } = this.deps.policy();
+    return authoritative && value.autoUpdate;
+  }
+  schedule(initial = false) {
+    if (!this.enabled() || this.timer || this.waiting) return;
+    const delay = initial ? Math.round(5e3 + (this.deps.random ?? Math.random)() * 25e3) : nextAutoUpdateDelayMs(this.failures, this.deps.random);
+    this.timer = this.setTimer(() => {
+      this.timer = null;
+      void this.runNow();
+    }, delay);
+    this.timer.unref?.();
+  }
+  cancel() {
+    if (this.timer) this.clearTimer(this.timer);
+    this.timer = null;
+  }
+  fail(error) {
+    this.failures++;
+    this.deps.status("failure", { reason: error instanceof Error ? error.message : String(error) });
+    this.schedule();
+  }
+  async decide(deferred) {
+    const facts = await this.deps.facts();
+    if (!this.enabled()) return;
+    const plan = this.deps.plan(facts);
+    if (plan.action === "up-to-date") {
+      this.failures = 0;
+      this.deps.status("verified-success", { latestVersion: facts.latest ?? void 0, reason: void 0 });
+      this.schedule();
+      return;
+    }
+    if (plan.action === "refused") {
+      this.deps.status("unsupported", { reason: plan.reason });
+      this.schedule();
+      return;
+    }
+    if (plan.action === "wait") {
+      this.deps.status("waiting-for-idle", { latestVersion: plan.latest, reason: void 0 });
+      this.defer();
+      return;
+    }
+    this.deps.status("running", { latestVersion: plan.latest, reason: void 0 });
+    const restarted = await this.install(plan, true);
+    if (restarted) this.deps.status("restarting", { latestVersion: plan.latest, reason: void 0 });
+    else if (!deferred) this.defer(plan.latest);
+  }
+  defer(latest) {
+    if (this.waiting) return;
+    this.waiting = true;
+    this.timer = this.setTimer(() => {
+      this.timer = null;
+      void (async () => {
+        this.waiting = false;
+        try {
+          if (!await this.deps.refreshPolicy() || !this.enabled()) {
+            this.deps.status("offline", { reason: "The owner policy could not be refreshed; automatic update is deferred." });
+            return;
+          }
+          await this.decide(true);
+        } catch (error) {
+          this.fail(error);
+        }
+      })();
+    }, 15e3);
+    this.timer.unref?.();
+    this.deps.status("waiting-for-idle", latest ? { latestVersion: latest } : void 0);
+  }
+  async install(plan, automatic) {
+    if (this.installing) return false;
+    this.installing = true;
+    try {
+      return await this.deps.installAndRestart(plan, automatic);
+    } finally {
+      this.installing = false;
+    }
+  }
+};
+var RelayMutationAdmission = class {
+  draining = false;
+  inFlight = 0;
+  waiters = [];
+  begin() {
+    if (this.draining) return null;
+    this.inFlight++;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.inFlight--;
+      if (this.inFlight === 0) {
+        for (const wake of this.waiters.splice(0)) wake();
+      }
+    };
+  }
+  async drain() {
+    this.draining = true;
+    if (this.inFlight === 0) return;
+    await new Promise((resolve5) => this.waiters.push(resolve5));
+  }
+  resume() {
+    this.draining = false;
+  }
+};
+
 // 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]);
@@ -1415,13 +1871,44 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
   if (!pagsToken) throw new Error("PAGS token required for WebSocket relay");
   const runnerNode = hostname3();
   const machine = loadMachineIdentity(runnerNode);
+  const autoUpdateKey = machine.id ? autoUpdatePolicyKey(machine.id) : "";
+  let autoUpdatePolicy = autoUpdateKey ? loadAutoUpdatePolicy(autoUpdateKey) ?? { autoUpdate: false } : { autoUpdate: false };
+  let autoUpdatePolicyAuthoritative = false;
+  let refreshingAutomaticPolicy = false;
+  let scheduleAutomaticUpdate = () => void 0;
+  const saveAutoUpdateStatus = (status, extra = {}) => {
+    autoUpdatePolicy = {
+      ...autoUpdatePolicy,
+      ...extra,
+      status,
+      lastAttemptAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (autoUpdateKey) saveAutoUpdatePolicy(autoUpdateKey, autoUpdatePolicy);
+  };
+  const acceptAutoUpdatePolicy = (response) => {
+    if (!autoUpdateKey) return;
+    const policy = policyFromResponse(response);
+    if (!policy) return;
+    const action = policyScheduleAction(autoUpdatePolicy, policy, autoUpdatePolicyAuthoritative);
+    autoUpdatePolicy = { ...autoUpdatePolicy, ...policy };
+    autoUpdatePolicyAuthoritative = true;
+    if (autoUpdateKey) saveAutoUpdatePolicy(autoUpdateKey, autoUpdatePolicy);
+    if (action === "cancel") {
+      scheduleAutomaticUpdate(false, true);
+      return;
+    }
+    if (refreshingAutomaticPolicy) return;
+    if (action === "start") {
+      scheduleAutomaticUpdate(true);
+    }
+  };
   const capabilities = await requestRunner("GET", "/capabilities", { url: localUrl, token: runnerToken, instanceId: instanceIds[0] });
   const caps = Array.isArray(capabilities.capabilities) ? capabilities.capabilities.filter((item) => typeof item === "string") : [];
   const registered = /* @__PURE__ */ new Set();
   let lastRegisterError = "";
   const registerRuntime = async (id, forceClaim = force) => {
     try {
-      await requestPags("POST", `/v1/instances/${apiPathSegment(id)}/runtime`, opts, {
+      const result = await requestPags("POST", `/v1/instances/${apiPathSegment(id)}/runtime`, opts, {
         endpointUrl: localUrl,
         token: runnerToken,
         placement: "local",
@@ -1430,8 +1917,14 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
         runnerNode,
         machineId: machine.id,
         machineNames: machine.names,
-        force: forceClaim
+        force: forceClaim,
+        autoUpdateStatus: {
+          status: autoUpdateStatusWire(autoUpdatePolicy.status),
+          latestVersion: autoUpdatePolicy.latestVersion,
+          error: autoUpdatePolicy.reason
+        }
       });
+      acceptAutoUpdatePolicy(result);
       registered.add(id);
       return true;
     } catch (e) {
@@ -1442,6 +1935,17 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
       return false;
     }
   };
+  const refreshAutomaticPolicy = async () => {
+    const id = registered.values().next().value;
+    if (!id) return false;
+    autoUpdatePolicyAuthoritative = false;
+    refreshingAutomaticPolicy = true;
+    try {
+      return await registerRuntime(id) && autoUpdatePolicyAuthoritative;
+    } finally {
+      refreshingAutomaticPolicy = false;
+    }
+  };
   const attached = /* @__PURE__ */ new Map();
   const processStartedAt = Date.now();
   const starts24h = recordRunnerStart(processStartedAt);
@@ -1455,43 +1959,190 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
   };
   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: [] }));
+    const [sessionsResult, healthResult] = await Promise.allSettled([
+      requestRunner("GET", "/coding/sessions", {
+        url: localUrl,
+        token: runnerToken,
+        instanceId: instanceIds[0]
+      }),
+      requestRunner("GET", "/health", { url: localUrl, token: runnerToken, instanceId: instanceIds[0] })
+    ]);
+    const observationsUnavailable = sessionsResult.status !== "fulfilled" || healthResult.status !== "fulfilled" || !healthResult.value.work;
+    const sessions = sessionsResult.status === "fulfilled" ? sessionsResult.value : { sessions: [] };
+    const health = healthResult.status === "fulfilled" ? healthResult.value : {};
+    const activeCoding = (sessions.sessions ?? []).filter((s) => s.alive && s.runState && s.runState !== "idle").map((s) => s.sessionId);
+    const localRuns = health.work?.localRuns ?? 0;
+    const codingTurns = health.work?.codingTurns ?? 0;
     return {
       current: CLI_VERSION,
       latest: await latestPublishedVersion(),
       fromSource: runsFromSource(),
       restarter: restarterFrom(process.env),
-      busy: (sessions.sessions ?? []).filter((s) => s.alive && s.runState && s.runState !== "idle").map((s) => s.sessionId)
+      // A restart ends browser/application work too. Give these durable names to the same
+      // planner so neither manual nor automatic update can mistake them for an idle machine.
+      busy: observationsUnavailable ? ["runner-work-observation-unavailable"] : [...activeCoding, ...Array.from({ length: codingTurns }, (_v, i) => `coding-turn-${i + 1}`), ...Array.from({ length: localRuns }, (_v, i) => health.work?.detail?.[i] || `local-run-${i + 1}`)]
     };
   };
-  const installAndRestart = async (plan) => {
-    writeLine(`Updating ${plan.current} \u2192 ${plan.latest} (runner_update)\u2026`);
-    await installVersion(plan.latest);
+  let updateInstallInFlight = false;
+  let installedPendingRestart = null;
+  const relayMutationAdmission = new RelayMutationAdmission();
+  const installAndRestart = async (plan, automatic = false) => {
+    if (updateInstallInFlight) return false;
+    updateInstallInFlight = true;
+    if (automatic && (!await refreshAutomaticPolicy() || !autoUpdatePolicy.autoUpdate)) {
+      updateInstallInFlight = false;
+      return false;
+    }
+    if (installedPendingRestart !== plan.latest) {
+      writeLine(`Updating ${plan.current} \u2192 ${plan.latest} (runner_update)\u2026`);
+      try {
+        await installVersion(plan.latest);
+        installedPendingRestart = plan.latest;
+      } catch (error) {
+        updateInstallInFlight = false;
+        throw error;
+      }
+    }
+    if (automatic) {
+      await relayMutationAdmission.drain();
+      await new Promise((resolve5) => setTimeout(resolve5, 500));
+      if (!await refreshAutomaticPolicy() || !autoUpdatePolicy.autoUpdate) {
+        relayMutationAdmission.resume();
+        updateInstallInFlight = false;
+        return false;
+      }
+    }
+    const finalFacts = await updateFacts();
+    if (finalFacts.busy.length || automatic && !mayAutomaticallyRestart({ authoritative: autoUpdatePolicyAuthoritative, enabled: autoUpdatePolicy.autoUpdate, workObserved: !finalFacts.busy.includes("runner-work-observation-unavailable"), busy: finalFacts.busy })) {
+      relayMutationAdmission.resume();
+      updateInstallInFlight = false;
+      return false;
+    }
     writeLine(`Installed ${plan.latest} \u2014 restarting; every agent re-attaches on the way back up.`);
-    setTimeout(() => {
-      for (const id of [...attached.keys()]) detach(id);
-      leaveForRestart(plan.restarter);
-    }, 500).unref();
+    for (const id of [...attached.keys()]) detach(id);
+    leaveForRestart(plan.restarter);
+    return true;
   };
   let updateWaiting = false;
-  const updateWhenIdle = () => {
+  const updateWhenIdle = (automatic = false) => {
     if (updateWaiting) return;
     updateWaiting = true;
     const until = Date.now() + 60 * 6e4;
     const tick = () => setTimeout(async () => {
+      if (automatic && (!await refreshAutomaticPolicy() || !autoUpdatePolicy.autoUpdate)) {
+        saveAutoUpdateStatus("offline", { reason: "The owner policy could not be refreshed; automatic update is deferred." });
+        updateWaiting = false;
+        return;
+      }
       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)}`));
+        if (automatic && !autoUpdatePolicy.autoUpdate) {
+          updateWaiting = false;
+          return;
+        }
+        if (automatic) saveAutoUpdateStatus("running", { latestVersion: plan.latest, reason: void 0 });
+        const installed = await installAndRestart(plan, automatic).catch((e) => {
+          if (automatic) saveAutoUpdateStatus("failure", { reason: e instanceof Error ? e.message : String(e) });
+          writeError(`runner_update: install failed \u2014 ${e instanceof Error ? e.message : String(e)}`);
+          return false;
+        });
+        if (automatic && !installed && Date.now() < until) {
+          saveAutoUpdateStatus("waiting-for-idle", { latestVersion: plan.latest });
+          tick();
+        } else updateWaiting = false;
+      } else if (plan.action === "wait" && Date.now() < until) {
+        if (automatic) saveAutoUpdateStatus("waiting-for-idle", { latestVersion: plan.latest, reason: void 0 });
+        tick();
+      } else {
+        if (automatic && plan.action === "refused") saveAutoUpdateStatus("unsupported", { reason: plan.reason });
         updateWaiting = false;
-      } else if (plan.action === "wait" && Date.now() < until) tick();
-      else updateWaiting = false;
+      }
     }, 15e3).unref();
     tick();
   };
+  let automaticTimer = null;
+  let automaticChecking = false;
+  let automaticFailures = 0;
+  const runAutomaticUpdateCheck = async () => {
+    if (!autoUpdatePolicy.autoUpdate || !autoUpdatePolicyAuthoritative || automaticChecking || updateWaiting) return;
+    automaticChecking = true;
+    try {
+      if (!await refreshAutomaticPolicy() || !autoUpdatePolicy.autoUpdate) {
+        saveAutoUpdateStatus("offline", { reason: "The owner policy could not be refreshed; automatic update is deferred." });
+        scheduleAutomaticUpdate();
+        return;
+      }
+      saveAutoUpdateStatus("checking", { reason: void 0 });
+      const facts = await updateFacts();
+      if (!autoUpdatePolicy.autoUpdate || !autoUpdatePolicyAuthoritative) return;
+      if (!facts.latest) {
+        automaticFailures++;
+        saveAutoUpdateStatus("failure", { reason: "Could not check the trusted npm registry for a newer CLI release." });
+        scheduleAutomaticUpdate();
+        return;
+      }
+      automaticFailures = 0;
+      const plan = planRunnerUpdate(facts);
+      if (plan.action === "up-to-date") {
+        saveAutoUpdateStatus("verified-success", { latestVersion: facts.latest, reason: void 0 });
+        scheduleAutomaticUpdate();
+        return;
+      }
+      if (plan.action === "refused") {
+        saveAutoUpdateStatus("unsupported", { latestVersion: facts.latest, reason: plan.reason });
+        scheduleAutomaticUpdate();
+        return;
+      }
+      if (plan.action === "wait") {
+        saveAutoUpdateStatus("waiting-for-idle", { latestVersion: plan.latest, reason: void 0 });
+        updateWhenIdle(true);
+        return;
+      }
+      if (!autoUpdatePolicy.autoUpdate || !autoUpdatePolicyAuthoritative) return;
+      saveAutoUpdateStatus("running", { latestVersion: plan.latest, reason: void 0 });
+      try {
+        const installed = await installAndRestart(plan, true);
+        if (!installed) {
+          saveAutoUpdateStatus("waiting-for-idle", { latestVersion: plan.latest });
+          updateWhenIdle(true);
+          return;
+        }
+        saveAutoUpdateStatus("restarting", { latestVersion: plan.latest, reason: void 0 });
+      } catch (e) {
+        automaticFailures++;
+        saveAutoUpdateStatus("failure", { latestVersion: plan.latest, reason: e instanceof Error ? e.message : String(e) });
+        scheduleAutomaticUpdate();
+      }
+    } finally {
+      automaticChecking = false;
+    }
+  };
+  scheduleAutomaticUpdate = (initial = false, cancel = false) => {
+    if (cancel || !autoUpdatePolicy.autoUpdate || !autoUpdatePolicyAuthoritative) {
+      if (automaticTimer) clearTimeout(automaticTimer);
+      automaticTimer = null;
+      return;
+    }
+    if (automaticTimer || updateWaiting) return;
+    const delay = initial ? Math.round(5e3 + Math.random() * 25e3) : nextAutoUpdateDelayMs(automaticFailures);
+    automaticTimer = setTimeout(() => {
+      automaticTimer = null;
+      void runAutomaticUpdateCheck();
+    }, delay);
+    automaticTimer.unref();
+  };
+  const automaticUpdateController = new AutomaticUpdateController({
+    policy: () => ({ value: autoUpdatePolicy, authoritative: autoUpdatePolicyAuthoritative }),
+    refreshPolicy: refreshAutomaticPolicy,
+    facts: updateFacts,
+    plan: planRunnerUpdate,
+    // This bridge is deliberately the same function used by explicit runner_update. It owns npm,
+    // a fresh authoritative policy, the mutation drain, final local-work observation and restart.
+    installAndRestart,
+    status: saveAutoUpdateStatus
+  });
+  scheduleAutomaticUpdate = (initial = false, cancel = false) => automaticUpdateController.onPolicy(cancel ? "cancel" : initial ? "start" : "keep");
+  if (autoUpdatePolicyAuthoritative && autoUpdatePolicy.autoUpdate) scheduleAutomaticUpdate(true);
   const answerUpdate = async (body) => {
     const dryRun = body?.dryRun === true;
     const plan = planRunnerUpdate(await updateFacts());
@@ -1501,7 +2152,7 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
       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);
+      if (!await automaticUpdateController.installManually(plan)) return { status: 409, result: { error: "A runner update is already installing or restarting." } };
     } catch (e) {
       return { status: 500, result: { error: `npm could not install ${plan.latest}: ${e instanceof Error ? e.message : String(e)}` } };
     }
@@ -1567,7 +2218,10 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
           reportRegistration();
         },
         answerControl,
-        runnerNode
+        runnerNode,
+        // The final automatic-update drain is an admission gate, not merely another poll:
+        // command work starts only when the old runner is still permitted to serve it.
+        () => relayMutationAdmission.begin()
       )
     );
     if (label) writeLine(`Attached agent: ${label}`);
@@ -1612,7 +2266,17 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
       });
       for (const id of [...attached.keys()]) {
         try {
-          await requestPags("POST", `/v1/instances/${apiPathSegment(id)}/runtime/heartbeat`, opts, { runnerNode, resources });
+          const response = await requestPags("POST", `/v1/instances/${apiPathSegment(id)}/runtime/heartbeat`, opts, {
+            runnerNode,
+            machineId: machine.id,
+            resources,
+            autoUpdateStatus: {
+              status: autoUpdateStatusWire(autoUpdatePolicy.status),
+              latestVersion: autoUpdatePolicy.latestVersion,
+              error: autoUpdatePolicy.reason
+            }
+          });
+          acceptAutoUpdatePolicy(response);
         } catch (e) {
           failure = e instanceof Error ? e.message : String(e);
         }
@@ -1701,7 +2365,7 @@ async function readSessionResources(localUrl, runnerToken) {
 }
 var RTT_PROBE_PREFIX = "rtt:";
 var RTT_ECHO_PREFIX = "rtt-echo:";
-function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, force = false, onConflict, onOpen, onControl, runnerNode = hostname3()) {
+function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, force = false, onConflict, onOpen, onControl, runnerNode = hostname3(), beginMutation = () => () => void 0) {
   let backoffMs = 1e3;
   let reconnecting = false;
   let closed = false;
@@ -1769,6 +2433,14 @@ function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, f
         return;
       }
       const method = (cmd.method || "POST").toUpperCase();
+      const releaseMutation = method !== "GET" && method !== "HEAD" ? beginMutation() : null;
+      if (method !== "GET" && method !== "HEAD" && !releaseMutation) {
+        try {
+          ws.send(JSON.stringify({ id: cmd.id, status: 503, result: { error: "Runner is draining for a safe automatic update; retry shortly." } }));
+        } catch {
+        }
+        return;
+      }
       const hasBody = method !== "GET" && method !== "HEAD" && cmd.body !== void 0;
       try {
         const headers = {};
@@ -1796,6 +2468,8 @@ function openRelaySocket(instanceId, wsBase, mintToken, localUrl, runnerToken, f
           ws.send(JSON.stringify({ id: cmd.id, status: 500, error: err instanceof Error ? err.message : String(err) }));
         } catch {
         }
+      } finally {
+        releaseMutation?.();
       }
     };
     ws.onclose = (ev) => {
@@ -1862,202 +2536,6 @@ 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 = []) {

package/package.json

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