@rackbops/ac-agent 2.0.0-alpha.60 → 2.0.0-alpha.62

package/README.md

@@ -267,9 +267,8 @@ curl -k https://127.0.0.1:8788/v1/health
 #### A server host that also runs the console (#826)
 
 The machine that runs the console in Docker can pair an agent too, so its own toolchain is graded in
-the Agents panel's Environment section like any other machine's; nucbox is set up this way (#826; its pairing was still pending on
-2026-10-20). It installs
-the Linux way above, with these differences.
+the Agents panel's Environment section like any other machine's; nucbox is set up this way and paired
+(#826, 2026-10-20). It installs the Linux way above, with these differences.
 
 **Node 26 from NodeSource's apt repository.** The agent needs Node 26 or newer (`engines.node`, #827;
 see **Install** above), the fleet's one line, and Ubuntu's own `nodejs` is older (22 on Ubuntu 26.04).
@@ -342,9 +341,12 @@ either: it shows on any `behind` row whose tool the standard gives a package for
 (among `git`, `gh`, `node` and `claude`; a `docker` or `cloudflared` row gets one too, and the agent
 runs that upgrade at the next 05:00 America/New_York, #978). The grant is what lets
 a click succeed; without it the agent refuses with `agent.toolchain.upgrade is not granted to agents on
-<machine>`. That one granted verb installs a package the standard names: as root, through `sudo apt-get
+<machine>`. That granted verb installs a package the standard names: as root, through `sudo apt-get
 install --only-upgrade` and the sudoers rule, or for Claude Code with its own `claude update` as the
-agent's user. No other verb is granted: no `agent.exec.*`, `agent.git.*` or `agent.scan.*`.
+agent's user. No other verb is granted to `agents`: no `agent.exec.*`, `agent.git.*` or `agent.scan.*`.
+
+nucbox additionally grants `agent.tunnel.lint` to the `admin` plugin, and nothing else (the owner's Grants
+screenshot, 2026-10-20).
 
 The console no longer asks this machine for what it has not been granted (#843):
 - The host's job runner skips a machine that has not granted every capability a job declares: no
@@ -483,7 +485,9 @@ running agent. Both outcomes are written to `agent.log`, as `replaced stale lock
 
 `stop`, `uninstall` and an install's restart kill only the pid that pinned answer names. When nothing
 answers they kill nothing and remove the stale `agent.pid`, and they print `... nothing was killed` if
-that pid belongs to some other live process.
+that pid belongs to some other live process. When the pinned answer has no `pid` (an agent older than
+alpha.59), they refuse and name the port and version instead of killing nothing. An install also
+refuses to start while the port still answers after the stop.
 
 ## Config and state directories
 

package/dist/ac-agent.mjs

@@ -47,7 +47,7 @@ function _mergeNamespaces(n, m) {
 }
 
 var name = "@rackbops/ac-agent";
-var version = "2.0.0-alpha.60";
+var version = "2.0.0-alpha.62";
 var type = "module";
 var description = "The per-machine host agent (installed with npx @rackbops/ac-agent): an HTTPS health server plus install/status/uninstall for a Windows logon task or a systemd user unit.";
 var bin = {
@@ -17808,13 +17808,15 @@ function writeConfig(dir, config, deps) {
  * pinned by the state dir's own `cert.pem`, with its own pid in the body.
  *
  * A null answer means "no agent of this state dir answers", never "the pid is dead": a process that
- * is starting up, or wedged, answers nothing either. Callers decide what null means for them.
+ * is starting up, or wedged, answers nothing either. Callers decide what null means for them. A
+ * non-null answer with `pid: null` means "an agent answers but cannot be named" (#1057): an agent
+ * older than #704 (alpha.57/58) answers ok without a pid.
  */
 /** The `serve`-time probe budget. Short, because the Windows launcher retries for a minute and the
  *  probe sits on the start path; `stop` and the service paths use `pinnedFetchHealth`'s 10 s. */
 const LOCK_PROBE_TIMEOUT_MS = 2000;
-/** The pid the agent answering this state dir's port reports, or null when none answers. */
-async function probeAgentPid(deps) {
+/** The agent answering this state dir's port, pinned by its own `cert.pem`, or null when none answers. */
+async function probeAgent(deps) {
     const certPem = deps.readFile(path.join(deps.stateDir, "cert.pem"));
     if (certPem === null)
         return null;
@@ -17826,10 +17828,18 @@ async function probeAgentPid(deps) {
         return null;
     }
     const health = await deps.fetchHealth(deps.port, certPem, fp, deps.bind);
-    if (health?.ok === true && Number.isInteger(health.pid) && health.pid > 1) {
-        return health.pid;
-    }
-    return null;
+    if (health?.ok !== true)
+        return null;
+    const pid = Number.isInteger(health.pid) && health.pid > 1 ? health.pid : null;
+    return {
+        pid,
+        version: typeof health.version === "string" ? health.version : null,
+        port: deps.port,
+    };
+}
+/** The pid the agent answering this state dir's port reports, or null when none answers or it reports none. */
+async function probeAgentPid(deps) {
+    return (await probeAgent(deps))?.pid ?? null;
 }
 
 /**
@@ -67292,6 +67302,28 @@ async function confirmHealthy(deps, port, certPem, expectedFingerprint, expected
     }
     throw new Error(`new process did not answer a health check on port ${port}`);
 }
+/** An agent still answers this state dir's port and this install cannot stop it (#1057): starting a new one would only fail to bind. */
+class AgentNotStoppedError extends Error {
+}
+const STOP_CONFIRM_BUDGET = { attempts: 10, delayMs: 300 };
+/** Waits for the stopped agent to stop answering (#1057): a SIGTERM'd agent takes a moment to
+ *  release the port, so one immediate probe could refuse falsely. Pinned by this state dir's cert,
+ *  so a foreign process on the port is not detected. */
+async function confirmStopped(deps) {
+    const budget = deps.stopConfirmBudget ?? STOP_CONFIRM_BUDGET;
+    let last = null;
+    for (let attempt = 0; attempt < budget.attempts; attempt++) {
+        last = await deps.probeAgent();
+        if (last === null)
+            return;
+        if (attempt < budget.attempts - 1) {
+            await new Promise((resolve) => setTimeout(resolve, budget.delayMs));
+        }
+    }
+    if (last === null)
+        return;
+    throw new AgentNotStoppedError(`port ${last.port} still answers version ${last.version ?? "unknown"}${last.pid !== null ? ` (pid ${last.pid})` : ""} after the stop; stop it by hand, then run ac-agent start`);
+}
 async function installService(deps) {
     if (deps.reposRootOverride !== undefined) {
         requireAbsolute(deps.reposRootOverride, "--repos-root");
@@ -67344,6 +67376,7 @@ async function installService(deps) {
     }
     const bundlePath = bundleTargetPath(deps.stateDir);
     const backupPath = bundleBackupPath(deps.stateDir);
+    const hadBundle = deps.exists(bundlePath);
     // #659: an install over a running agent keeps the bundle it is replacing, and the version that
     // bundle is serving, so a new bundle that never comes up can be undone. Read before the copy: once
     // the copy lands, the file on disk is no longer what the running process loaded.
@@ -67439,12 +67472,20 @@ async function installService(deps) {
         let restartError = null;
         try {
             await stopService(deps);
+            await confirmStopped(deps);
             await deps.platform.start();
             await confirmHealthy(deps, port, certPem, fp, deps.version, budget, loaded.config.bind);
         }
         catch (err) {
             restartError = err;
         }
+        if (restartError instanceof AgentNotStoppedError) {
+            // #1057: nothing was started, so there is nothing to roll back (and `rollBack`'s own stop would
+            // refuse the same way). The new bundle stays registered; the operator's `ac-agent start` after
+            // stopping the old process by hand brings it up.
+            record("failed", restartError.message);
+            throw restartError;
+        }
         if (restartError === null) {
             // Recorded only after the restart sequence: a failed record write must never look like a
             // failed restart (#659 review round 1).
@@ -67477,7 +67518,12 @@ async function installService(deps) {
     // Nothing was running to restart (the agent died between the pre-check and now, or a fresh install).
     // Under --update the agent that launched this install was running, so this is a failure the record
     // must say, not leave at `installing` (#659 review round 2).
-    record("failed", "no agent was running after the install; run ac-agent start");
+    const noAgent = "no agent was running after the install; run ac-agent start";
+    // #1057: an install over an existing bundle says why it did not restart. A first-ever install stays
+    // quiet, and so does Linux, where `platform.install`'s `enable --now` is already starting the unit.
+    if (hadBundle && deps.osPlatform !== "linux")
+        deps.print(noAgent);
+    record("failed", noAgent);
 }
 function nowIso(deps) {
     return (deps.now ?? (() => new Date()))().toISOString();
@@ -67643,7 +67689,8 @@ function readAgentPid(deps) {
  *  `killProcess`'s doc for why this doesn't rely on the service manager's stop to reach the agent.
  *  With no lock file it still probes and kills an answering agent (#1052). When the pinned health probe answers, its pid is killed (with
  *  the mismatch printed if the lock named another); when nothing answers, nothing is killed, and
- *  that is printed if the lock's pid belongs to a live process. */
+ *  that is printed if the lock's pid belongs to a live process. A pidless answer (an agent older
+ *  than #704) throws `AgentNotStoppedError` instead of killing nothing silently (#1057). */
 async function killRunningAgent(deps) {
     const pid = readAgentPid(deps);
     // Probed even with no usable lock file (#1052): an agent whose `agent.pid` was lost or replaced by a
@@ -67655,10 +67702,13 @@ async function killRunningAgent(deps) {
         }
         return;
     }
-    if (pid !== null && answering !== pid) {
-        deps.print(`agent.pid names pid ${pid}, but the agent answering on its port is pid ${answering}; stopping pid ${answering}`);
+    if (answering.pid === null) {
+        throw new AgentNotStoppedError(`an agent answers on port ${answering.port} (version ${answering.version ?? "unknown"}) but does not report its pid; stop it by hand, then retry`);
     }
-    deps.killProcess(answering);
+    if (pid !== null && answering.pid !== pid) {
+        deps.print(`agent.pid names pid ${pid}, but the agent answering on its port is pid ${answering.pid}; stopping pid ${answering.pid}`);
+    }
+    deps.killProcess(answering.pid);
 }
 /** Whether the agent is currently serving: a live pid in `agent.pid`, probed with `deps.isAlive`
  *  (the same `process.kill(pid, 0)` semantics `lock.ts`'s `acquire()` uses, rather than trusting the
@@ -67670,8 +67720,8 @@ function isAgentRunning(deps) {
     const pid = readAgentPid(deps);
     return pid !== null && deps.isAlive(pid);
 }
-/** Whether an agent is serving, by either signal: a live pid in `agent.pid`, or an agent of this state
- *  dir answering its port (#1052). The pid file alone is not enough: a starter that lost the port bind
+/** Whether an agent is serving, by either signal: a live pid in `agent.pid`, or any pinned ok answer
+ *  on this state dir's port, with or without a pid (#1052, #1057). The pid file alone is not enough: a starter that lost the port bind
  *  leaves its own dead pid in it while the old agent keeps serving, and an install that trusts the file
  *  then skips the stop/start and reports "no agent was running" with the old bundle still live. */
 async function isAgentServing(deps) {
@@ -67705,7 +67755,9 @@ async function stopService(deps, options = {}) {
  *  command stops and disables the unit together, in one call, rather than as a separate step. Either
  *  way this is a harmless redundant stop against an already-stopped service, not a second attempt
  *  worth engineering around. A failing stop here (the unit or task is not loaded) is tolerated so the
- *  rest of the teardown still runs (#710); the `stop` verb reports it (#709). */
+ *  rest of the teardown still runs (#710); the `stop` verb reports it (#709). A pidless answering
+ *  agent makes `killRunningAgent` throw, so uninstall rejects before any teardown (#1057): deleting
+ *  `cert.pem` would remove the only way to ever identify that agent. */
 async function uninstall(deps, options) {
     await stopService(deps, { tolerateStopFailure: true });
     await deps.platform.uninstall();
@@ -67723,6 +67775,7 @@ async function uninstall(deps, options) {
 
 var index$2 = /*#__PURE__*/Object.freeze({
   __proto__: null,
+  AgentNotStoppedError: AgentNotStoppedError,
   detectVirtualization: detectVirtualization,
   installService: installService,
   isAgentRunning: isAgentRunning,
@@ -68337,6 +68390,20 @@ function processIsAlive(pid) {
         return false;
     }
 }
+/** `ServiceDeps.killProcess` (#1057): an already-gone pid (ESRCH) is fine; anything else (EPERM on Windows) is printed, never swallowed. */
+function killProcessFn(kill, warn) {
+    return (pid) => {
+        try {
+            kill(pid);
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === "ESRCH")
+                return;
+            warn(`could not stop pid ${pid}: ${code ?? (err instanceof Error ? err.message : String(err))}`);
+        }
+    };
+}
 /** One child-process runner shape for both platforms: Windows pipes a script to powershell.exe's
  * stdin, Linux runs `cmd args` directly. Constructed once per CLI invocation, reused by every
  * PlatformOps method (install/uninstall/state/stop/start) instead of re-implemented per call. */
@@ -68561,14 +68628,7 @@ async function buildServiceDeps(overrides = {}) {
         removeDir: (p) => {
             fs.rmSync(p, { recursive: true, force: true });
         },
-        killProcess: (pid) => {
-            try {
-                process.kill(pid);
-            }
-            catch {
-                // already gone
-            }
-        },
+        killProcess: killProcessFn((pid) => process.kill(pid), (line) => process.stdout.write(`${line}\n`)),
         isAlive: processIsAlive,
         version: packageJson.version,
         hostname: os.hostname,
@@ -68593,7 +68653,7 @@ async function buildServiceDeps(overrides = {}) {
         fetchHealth: pinnedFetchHealth,
         // #704: dials the port the running agent was started on (`agent.toml` as loaded before any install
         // rewrites it), with the 10 s pin budget; `stop` and the restart paths can wait longer than `serve`.
-        probeAgent: () => probeAgentPid({
+        probeAgent: () => probeAgent({
             stateDir: dirs.stateDir,
             port: loaded.config.port,
             bind: loaded.config.bind,
@@ -81638,4 +81698,4 @@ var updater = /*#__PURE__*/Object.freeze({
   selfUpdateSupported: selfUpdateSupported
 });
 
-export { AGENT_API_VERSION, NODE_FLOOR, NO_CWD_EXE_SEARCH_VAR, applySpawnGuard, buildRepoFs, buildWhichFs, certWarningFor, checkEnvironment, dispatch, healthBaseUrl, healthResultFrom, isEntryPoint, main, makeRunners, pinnedFetchHealth, readFileFn, realExists, runningJobCount, toolchainUpgradeDeps };
+export { AGENT_API_VERSION, NODE_FLOOR, NO_CWD_EXE_SEARCH_VAR, applySpawnGuard, buildRepoFs, buildWhichFs, certWarningFor, checkEnvironment, dispatch, healthBaseUrl, healthResultFrom, isEntryPoint, killProcessFn, main, makeRunners, pinnedFetchHealth, readFileFn, realExists, runningJobCount, toolchainUpgradeDeps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/ac-agent",
-  "version": "2.0.0-alpha.60",
+  "version": "2.0.0-alpha.62",
   "private": false,
   "type": "module",
   "description": "The per-machine host agent (installed with npx @rackbops/ac-agent): an HTTPS health server plus install/status/uninstall for a Windows logon task or a systemd user unit.",