agent-dealer 1.2.4 → 1.2.6

package/dist/managed-update-restart.test.js

@@ -0,0 +1,227 @@
+// NOT-279: a managed update downloaded while Dealer runs stays pending until a safe
+// start/restart, and status reports the version the backend itself is running.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { readCurrentManagedVersion, readUpdateState, writeUpdateState } from "./managed/index.js";
+import { activateVersion } from "./managed/activate.js";
+import { cliEntryInVersionDir, versionDir } from "./managed/paths.js";
+import { runStart } from "./start.js";
+import { runStatus } from "./status.js";
+import { maybeCheckForUpdateOnRun } from "./update-check.js";
+import { getVersion } from "./version.js";
+const RUNNING = "1.0.0";
+const PENDING = "1.1.0";
+/** Stands in for an agent-dealer backend; `version` null mimics a build that predates /api/version. */
+async function startFakeBackend(version) {
+    const script = `
+const http = require("node:http");
+const version = ${JSON.stringify(version)};
+const server = http.createServer((req, res) => {
+  res.setHeader("content-type", "application/json");
+  if (req.url === "/api/version" && version === null) { res.statusCode = 404; res.end("{}"); return; }
+  res.end(JSON.stringify(req.url === "/api/version" ? { version } : { ok: true }));
+});
+server.listen(0, "127.0.0.1", () => console.log(server.address().port));
+`;
+    const child = spawn(process.execPath, ["-e", script], { stdio: ["ignore", "pipe", "inherit"] });
+    const port = await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.stdout.once("data", (chunk) => resolve(Number(String(chunk).trim())));
+    });
+    return { child, port };
+}
+async function freePort() {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.listen(0, "127.0.0.1", () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+    });
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A managed home with RUNNING active and PENDING downloaded. The pending CLI is a stub that
+ * records its argv, standing in for the new version's `agent-dealer start`.
+ */
+function seedManagedHome() {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "agent-dealer-managed-restart-"));
+    const reexecLog = path.join(home, "reexec.json");
+    process.env.AGENT_DEALER_HOME = home;
+    process.env.AGENT_DEALER_LOCAL_BIN = path.join(home, "local-bin");
+    for (const version of [RUNNING, PENDING]) {
+        const entry = cliEntryInVersionDir(versionDir(version));
+        fs.mkdirSync(path.dirname(entry), { recursive: true });
+        fs.writeFileSync(entry, `require("node:fs").writeFileSync(${JSON.stringify(reexecLog)}, JSON.stringify({ version: ${JSON.stringify(version)}, argv: process.argv.slice(2) }));\n`);
+    }
+    activateVersion(RUNNING);
+    // Fresh checkedAt: the entry hook's background check must not reach the registry.
+    writeUpdateState({ checkedAt: new Date().toISOString(), latest: PENDING, pendingVersion: PENDING });
+    return { home, reexecLog };
+}
+async function withManagedHome(env, fn) {
+    const keys = ["AGENT_DEALER_HOME", "AGENT_DEALER_LOCAL_BIN", "AGENT_DEALER_DISABLE_AUTOUPDATER", "AGENT_DEALER_SUPERVISOR", "PORT", "WEB_PORT", ...Object.keys(env)];
+    const saved = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
+    delete process.env.AGENT_DEALER_DISABLE_AUTOUPDATER;
+    delete process.env.AGENT_DEALER_SUPERVISOR;
+    delete process.env.WEB_PORT;
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    const managed = seedManagedHome();
+    try {
+        await fn(managed);
+    }
+    finally {
+        for (const [key, value] of Object.entries(saved)) {
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+        fs.rmSync(managed.home, { recursive: true, force: true });
+    }
+}
+async function captureOutput(fn) {
+    const original = { log: console.log, warn: console.warn, error: console.error };
+    const lines = [];
+    console.log = console.warn = console.error = (message) => {
+        lines.push(String(message));
+    };
+    try {
+        const code = await fn();
+        return { code, text: lines.join("\n") };
+    }
+    finally {
+        Object.assign(console, original);
+    }
+}
+function assertStillPending(managed) {
+    assert.equal(readCurrentManagedVersion(), RUNNING, "`current` must not switch under a live backend");
+    assert.equal(readUpdateState()?.pendingVersion, PENDING);
+    assert.equal(fs.existsSync(managed.reexecLog), false, "the pending version must not be launched");
+}
+test("pending version stays pending while a backend runs; status shows running A and pending B", async () => {
+    const { child, port } = await startFakeBackend(RUNNING);
+    try {
+        await withManagedHome({ PORT: String(port) }, async (managed) => {
+            assert.deepEqual(await maybeCheckForUpdateOnRun(), { upgraded: false });
+            const start = await captureOutput(() => runStart({ port }));
+            assert.equal(start.code, 0);
+            assert.match(start.text, /Already running/);
+            assert.match(start.text, new RegExp(`${PENDING} is downloaded but not active`));
+            assertStillPending(managed);
+            const status = await captureOutput(() => runStatus());
+            assert.equal(status.code, 0);
+            assert.match(status.text, new RegExp(`Agent Dealer version ${getVersion()}`), "NOT-224 installed line is kept");
+            assert.match(status.text, new RegExp(`running version ${RUNNING.replace(/\./g, "\\.")}`));
+            assert.match(status.text, new RegExp(`Pending +managed version ${PENDING.replace(/\./g, "\\.")}`));
+            assert.match(status.text, /Version mismatch: backend is running 1\.0\.0, installed CLI is/);
+            assert.match(status.text, /restart after current execution finishes/);
+            assertStillPending(managed);
+        });
+        assert.equal(isAlive(child.pid), true, "observing an update must not stop the backend");
+    }
+    finally {
+        child.kill("SIGKILL");
+    }
+});
+test("status says running version unknown for a backend without /api/version", async () => {
+    const { child, port } = await startFakeBackend(null);
+    try {
+        await withManagedHome({ PORT: String(port) }, async () => {
+            const status = await captureOutput(() => runStatus());
+            assert.equal(status.code, 0);
+            assert.match(status.text, /running version unknown/);
+            assert.doesNotMatch(status.text, new RegExp(`running version ${getVersion().replace(/\./g, "\\.")}`));
+            assert.doesNotMatch(status.text, /Version mismatch/);
+        });
+    }
+    finally {
+        child.kill("SIGKILL");
+    }
+});
+test("stopped backend: start activates the pending version before spawning and hands off to it", async () => {
+    const port = await freePort();
+    await withManagedHome({ PORT: String(port) }, async (managed) => {
+        const result = await captureOutput(() => runStart({ port }));
+        assert.equal(result.code, 0);
+        assert.match(result.text, new RegExp(`Activated managed version ${PENDING.replace(/\./g, "\\.")}`));
+        assert.equal(readCurrentManagedVersion(), PENDING);
+        assert.equal(readUpdateState()?.pendingVersion, null);
+        const handoff = JSON.parse(fs.readFileSync(managed.reexecLog, "utf8"));
+        assert.equal(handoff.version, PENDING);
+        assert.deepEqual(handoff.argv, ["start", "--port", String(port)]);
+    });
+});
+test("stopped backend: status reports the pending version for the next start", async () => {
+    const port = await freePort();
+    await withManagedHome({ PORT: String(port) }, async () => {
+        const status = await captureOutput(() => runStatus());
+        assert.equal(status.code, 1);
+        assert.match(status.text, /Status: not running/);
+        assert.match(status.text, /Update pending: 1\.1\.0 activates on the next `agent-dealer start`/);
+    });
+});
+test("start refuses to activate while the server's own pid marker is live, even if /health is down", async () => {
+    const port = await freePort();
+    await withManagedHome({ PORT: String(port) }, async (managed) => {
+        fs.writeFileSync(path.join(managed.home, "server.pid"), JSON.stringify({ pid: process.pid, port }));
+        const result = await captureOutput(() => runStart({ port }));
+        assert.equal(result.code, 1);
+        assert.match(result.text, /not activating/);
+        assertStillPending(managed);
+    });
+});
+for (const daemon of [false, true]) {
+    const label = daemon ? "start --daemon --force" : "start --force";
+    test(`${label}: failed stop leaves the pending version inactive and starts nothing`, async () => {
+        const { child, port } = await startFakeBackend(RUNNING);
+        try {
+            // No run.json in an isolated home = no proof of ownership, so stop leaves the listener up.
+            await withManagedHome({ PORT: String(port) }, async (managed) => {
+                const result = await captureOutput(() => runStart({ force: true, daemon, port }));
+                assert.equal(result.code, 1);
+                assertStillPending(managed);
+                assert.equal(fs.existsSync(path.join(managed.home, "run.json")), false);
+            });
+            assert.equal(isAlive(child.pid), true);
+        }
+        finally {
+            child.kill("SIGKILL");
+        }
+    });
+    test(`${label}: successful stop activates and starts the pending version`, async () => {
+        const { child, port } = await startFakeBackend(RUNNING);
+        try {
+            await withManagedHome({ PORT: String(port) }, async (managed) => {
+                fs.writeFileSync(path.join(managed.home, "run.json"), JSON.stringify({ host: "127.0.0.1", port, serverPid: child.pid, cliPid: 2 ** 22, startedAt: new Date().toISOString() }));
+                const result = await captureOutput(() => runStart({ force: true, daemon, port }));
+                assert.equal(result.code, 0, result.text);
+                assert.equal(readCurrentManagedVersion(), PENDING);
+                const handoff = JSON.parse(fs.readFileSync(managed.reexecLog, "utf8"));
+                assert.equal(handoff.version, PENDING);
+                assert.deepEqual(handoff.argv, ["start", "--force", "--port", String(port), ...(daemon ? ["--daemon"] : [])]);
+            });
+        }
+        finally {
+            child.kill("SIGKILL");
+        }
+    });
+}

package/dist/ports.d.ts

@@ -6,3 +6,9 @@ export declare function isTcpPortOpen(host: string, port: number): Promise<boole
 export declare function probeAgentDealer(host: string, port: number): Promise<AgentDealerProbe>;
 export declare function listListeningPids(port: number): number[];
 export declare function formatPortConflict(port: number, label: string, host: string, isAgentDealer: boolean): string;
+/**
+ * NOT-279: the version the live backend reports about itself, or null when it is down, the
+ * request fails, or it predates `/api/version`. Callers must show "unknown" for null —
+ * never substitute the installed CLI version, which may be ahead of the running server.
+ */
+export declare function fetchRunningBackendVersion(host: string, port: number): Promise<string | null>;

package/dist/ports.js

@@ -70,3 +70,13 @@ export function formatPortConflict(port, label, host, isAgentDealer) {
     return (`Port ${port} (${label}) is in use by another program on ${host}.${pidHint}\n` +
         `  • Free the port, or start on a different port: agent-dealer start --port <port>`);
 }
+/**
+ * NOT-279: the version the live backend reports about itself, or null when it is down, the
+ * request fails, or it predates `/api/version`. Callers must show "unknown" for null —
+ * never substitute the installed CLI version, which may be ahead of the running server.
+ */
+export async function fetchRunningBackendVersion(host, port) {
+    const body = await fetchJson(`http://${host}:${port}/api/version`);
+    const version = body?.version;
+    return typeof version === "string" && version.trim() ? version : null;
+}

package/dist/runtime-state.d.ts

@@ -10,3 +10,13 @@ export declare function readRunState(): RunState | null;
 export declare function writeRunState(state: RunState): void;
 export declare function clearRunState(): void;
 export declare function isProcessAlive(pid: number): boolean;
+/** The server's own liveness marker (packages/server/src/server-liveness.ts), written by
+ * every launch mode — not only by this CLI's supervisor like run.json. */
+export declare function serverPidMarkerPath(): string;
+/**
+ * NOT-279: whether a backend may still be serving this home — a healthy agent-dealer on the
+ * port, or a live owner of the server's pid marker (a backend still booting or draining
+ * holds the marker before/after it answers /health). Gate for switching the managed
+ * `current` version: activation must only happen when this is false.
+ */
+export declare function isBackendLive(host: string, port: number): Promise<boolean>;

package/dist/runtime-state.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { prodHomeDir } from "./env.js";
+import { probeAgentDealer } from "./ports.js";
 export function runStatePath() {
     return path.join(prodHomeDir(), "run.json");
 }
@@ -37,3 +38,28 @@ export function isProcessAlive(pid) {
         return false;
     }
 }
+/** The server's own liveness marker (packages/server/src/server-liveness.ts), written by
+ * every launch mode — not only by this CLI's supervisor like run.json. */
+export function serverPidMarkerPath() {
+    return path.join(prodHomeDir(), "server.pid");
+}
+function isServerPidMarkerLive() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(serverPidMarkerPath(), "utf8"));
+        return typeof raw.pid === "number" && isProcessAlive(raw.pid);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * NOT-279: whether a backend may still be serving this home — a healthy agent-dealer on the
+ * port, or a live owner of the server's pid marker (a backend still booting or draining
+ * holds the marker before/after it answers /health). Gate for switching the managed
+ * `current` version: activation must only happen when this is false.
+ */
+export async function isBackendLive(host, port) {
+    if ((await probeAgentDealer(host, port)).up)
+        return true;
+    return isServerPidMarkerLive();
+}

package/dist/start.js

@@ -3,7 +3,8 @@ import { loadProdEnvFile, prodEnvFilePath, prodHomeDir, resolveBundledListenPort
 import { appendDaemonLogLine, openDaemonLogFd, resolveCliEntry, resolveDaemonLogPath, resolveDaemonLogsDir, } from "./daemon-logs.js";
 import { formatPortConflict, isTcpPortOpen, probeAgentDealer } from "./ports.js";
 import { resolveServerEntry, resolveUiDist } from "./paths.js";
-import { clearRunState, writeRunState } from "./runtime-state.js";
+import { clearRunState, isBackendLive, writeRunState } from "./runtime-state.js";
+import { activatePendingVersion, cliEntryInVersionDir, readPendingManagedVersion, versionDir, } from "./managed/index.js";
 import { runStop } from "./stop.js";
 import { getVersion } from "./version.js";
 const children = [];
@@ -80,7 +81,10 @@ function printRunningEndpoints(base, uiDist) {
     console.log("");
 }
 function buildSupervisorArgs(options) {
-    const args = ["start", "--_supervisor"];
+    return ["start", "--_supervisor", ...buildStartFlags(options)];
+}
+function buildStartFlags(options) {
+    const args = [];
     if (options.open) {
         args.push("--open");
     }
@@ -117,6 +121,57 @@ async function runDaemonLauncher(options) {
     console.log("");
     return 0;
 }
+function printPendingWhileRunning() {
+    const pending = readPendingManagedVersion();
+    if (!pending)
+        return;
+    console.log(`Managed version ${pending} is downloaded but not active while this backend runs. ` +
+        "Restart after current execution finishes: agent-dealer start --force");
+}
+/** Runs `start` from the freshly activated version's CLI so its own server bundle is spawned. */
+function reexecStart(cliEntry, args) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [cliEntry, ...args], { stdio: "inherit", env: process.env });
+        const forward = (signal) => () => {
+            if (!child.killed)
+                child.kill(signal);
+        };
+        process.on("SIGINT", forward("SIGINT"));
+        process.on("SIGTERM", forward("SIGTERM"));
+        child.on("error", (err) => {
+            console.error(`[agent-dealer] Could not launch ${cliEntry}: ${err.message}`);
+            resolve(1);
+        });
+        child.on("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+}
+/**
+ * NOT-279: a managed update downloaded while Dealer ran stays pending until here — after the
+ * already-running check and any `--force` stop succeeded. Re-checks liveness (health probe +
+ * the server's own pid marker) so `current` never switches under a live backend, then hands
+ * off to the new version's CLI. Returns null when there is nothing to activate (continue in
+ * this process), otherwise the exit code to return.
+ */
+async function activatePendingBeforeSpawn(host, port, options) {
+    if (isSupervisorMode(options))
+        return null;
+    const pending = readPendingManagedVersion();
+    if (!pending)
+        return null;
+    if (await isBackendLive(host, port)) {
+        console.error(`[agent-dealer] Managed version ${pending} is pending, but a backend is still live for this home — not activating.`);
+        console.error("[agent-dealer] Stop it first (agent-dealer stop) or restart with: agent-dealer start --force");
+        return 1;
+    }
+    const { activated } = activatePendingVersion();
+    if (!activated)
+        return null;
+    console.log(`[agent-dealer] Activated managed version ${activated}`);
+    const args = ["start", ...buildStartFlags(options)];
+    if (options.daemon)
+        args.push("--daemon");
+    return reexecStart(cliEntryInVersionDir(versionDir(activated)), args);
+}
 async function ensurePortAvailable(host, port, probe) {
     const portBusy = await isTcpPortOpen(host, port);
     if (portBusy && !probe.up) {
@@ -172,6 +227,7 @@ export async function runStart(options = {}) {
             else {
                 printRunningEndpoints(base, uiDist);
                 console.log("Already running. Use `agent-dealer stop` or `agent-dealer start --daemon --force` to restart.");
+                printPendingWhileRunning();
                 return 0;
             }
         }
@@ -179,6 +235,10 @@ export async function runStart(options = {}) {
         if (portError !== null) {
             return portError;
         }
+        const handoff = await activatePendingBeforeSpawn(host, port, options);
+        if (handoff !== null) {
+            return handoff;
+        }
         return runDaemonLauncher(options);
     }
     const ioMode = supervisor ? "file" : "inherit";
@@ -193,6 +253,7 @@ export async function runStart(options = {}) {
         else {
             printRunningEndpoints(base, uiDist);
             console.log("Already running. Use `agent-dealer stop` or `agent-dealer start --force` to restart.");
+            printPendingWhileRunning();
             return 0;
         }
     }
@@ -200,6 +261,10 @@ export async function runStart(options = {}) {
     if (portError !== null) {
         return portError;
     }
+    const handoff = await activatePendingBeforeSpawn(host, port, options);
+    if (handoff !== null) {
+        return handoff;
+    }
     if (!uiDist) {
         const warnUi = "[agent-dealer] Dashboard UI bundle not found. API will still start.";
         const warnDist = "[agent-dealer] Set AGENT_DEALER_UI_DIST or run from a published npm package build.";

package/dist/status.js

@@ -1,24 +1,52 @@
-import { formatPortConflict, isTcpPortOpen, probeAgentDealer } from "./ports.js";
+import { fetchRunningBackendVersion, formatPortConflict, isTcpPortOpen, probeAgentDealer } from "./ports.js";
 import { isProcessAlive, readRunState } from "./runtime-state.js";
 import { getVersion } from "./version.js";
 import { loadProdEnvFile, resolveBundledListenPort } from "./env.js";
+import { readPendingManagedVersion } from "./managed/index.js";
+const RESTART_ACTION = "restart after current execution finishes: agent-dealer start --force";
 export async function runStatus() {
     loadProdEnvFile();
     const host = "127.0.0.1";
     const state = readRunState();
     const port = state?.port ?? resolveBundledListenPort();
     const probe = await probeAgentDealer(host, port);
-    console.log(`Agent Dealer version ${getVersion()}`);
+    const installed = getVersion();
+    console.log(`Agent Dealer version ${installed}`);
     console.log(`Configured host ${host}  port :${port}`);
     console.log("");
+    // NOT-279: the running version comes only from the backend itself. The installed CLI (and the
+    // managed `current` link) can be ahead of a server that was started before an update.
+    const running = probe.up ? await fetchRunningBackendVersion(host, port) : null;
+    const pending = readPendingManagedVersion();
     if (probe.up) {
         console.log("Status: running");
         console.log(`  Dashboard  ${probe.url}`);
         console.log(`  API health ${probe.url}/health`);
+        console.log(running
+            ? `  Backend    running version ${running}`
+            : "  Backend    running version unknown (backend did not report it — installed CLI version is not assumed)");
     }
     else {
         console.log("Status: not running");
     }
+    console.log(`  Installed  CLI version ${installed}`);
+    if (pending) {
+        console.log(`  Pending    managed version ${pending} (downloaded, not active)`);
+    }
+    if (probe.up) {
+        if (running && running !== installed) {
+            console.log("");
+            console.log(`Version mismatch: backend is running ${running}, installed CLI is ${installed} — ${RESTART_ACTION}`);
+        }
+        if (pending) {
+            console.log("");
+            console.log(`Update pending: ${pending} activates only on restart — ${RESTART_ACTION}`);
+        }
+    }
+    else if (pending) {
+        console.log("");
+        console.log(`Update pending: ${pending} activates on the next \`agent-dealer start\`.`);
+    }
     if (state) {
         console.log("");
         console.log("Last run.json:");

package/dist/update-check.js

@@ -44,12 +44,9 @@ function writeCache(next) {
 /** npm-global / unknown path — keep TTY prompt behavior. Managed uses hooks instead. */
 export async function maybeCheckForUpdateOnRun() {
     if (detectInstallKind() === "managed") {
-        const { activated } = runManagedCliEntryHooks({ allowActivate: true });
-        if (activated) {
-            console.log(`[agent-dealer] Activated managed version ${activated}`);
-            console.log("Re-run your command to use the new version.");
-            return { upgraded: true };
-        }
+        // NOT-279: download only. A pending version activates in `agent-dealer start`, once no
+        // backend is live — never from an arbitrary command while Dealer may be serving work.
+        runManagedCliEntryHooks();
         return { upgraded: false };
     }
     if (process.env.AGENT_DEALER_DISABLE_UPGRADE_CHECK === "1") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dealer",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "Human control plane for agent execution — queue, plan approval, audit",
   "license": "MIT",
   "type": "module",