@oddessentials/agent-guild 0.33.1 → 0.34.0

package/README.md

@@ -87,12 +87,16 @@ shell. Pick the default chip to clear a saved choice and follow the default
 again. The choice applies to new sessions.
 
 **See the manager environment.** The Shell card summarizes detected Node.js,
-Python, Go, .NET SDK, R and Rust versions. **Environment details** shows the
-resolved paths, detection results, .NET runtimes and detected nvm/NVM for
-Windows, vfox, uv and pnpm launchers. Tools are listed by presence; their
-activation is not inferred. This describes the computer running Agent Guild
-and its manager environment, including when viewed remotely. Selected shells,
-projects and existing sessions may use different versions.
+Python, Go, .NET SDK, R and Rust versions. **Environment details** opens on
+the manager result: resolved paths, detection results, .NET runtimes and
+detected nvm/NVM for Windows, vfox, uv and pnpm launchers. Tools are listed
+by presence; their activation is not inferred. The same dialog can show three
+other facts, each refreshed on its own: pin files in the working folder
+(configured text, not an installed version), the PATH a Guild session was
+given when it started, and the PATH a new process receives before the shell
+runs its startup files. tmux and herdr sessions have no spawn record to show.
+The card itself stays the manager summary. This describes the computer running
+Agent Guild, including when viewed remotely.
 
 Python always uses `python` when it is found on the manager's PATH; otherwise
 it uses `python3`. A broken `python` remains the primary result, with a
@@ -105,8 +109,10 @@ Discovery runs on first viewing and again on **Refresh**, in an isolated
 helper with a neutral temporary working directory. It does not load shell
 profiles, activate tools, download runtimes or modify installations. Unknown
 script/shim launchers and Windows execution aliases are left unverified.
-Refresh checks the manager's current environment; it does not reload its
-PATH from a shell. Existing results remain visible during refresh. Go reports
+Refresh checks the fact selected in the dialog and leaves the others as they
+are. The manager fact reads the manager's current environment and does not
+reload its PATH from a shell. Existing results for that fact remain visible
+during refresh. Go reports
 the local bundled toolchain with automatic switching disabled, and the Node
 version running Agent Guild is also shown in details.
 
@@ -233,6 +239,23 @@ does not start even while **Launch at sign-in** is checked. While it is on,
 the setting says when it last ran at sign-in and whether the session manager
 started then.
 
+On Linux the setting is one choice: **Only when I start it**, **When I sign
+in** (the desktop entry above) or **When the computer starts**. The last
+runs the session manager as a systemd user service, `agent-guild.service`,
+so it is running before you connect to a machine with no desktop, and
+systemd starts it again if it fails. Only one of the two starters is on at
+a time, and changing the choice never stops the running session manager: one
+started by hand hands over to systemd at its next restart. While the service
+is on, `agent-guild open` and `agent-guild restart` start the session manager
+through systemd, `agent-guild stop` stops it until the next start, and tmux
+cards survive restarts as they do without it. To start before anyone signs
+in, systemd needs lingering, which only an administrator can always turn
+on; the setting shows the command, `sudo loginctl enable-linger <user>`,
+until it is on. It also shows what systemd reports, such as a port another
+session manager was using, and for a failure the command that shows its
+log, `journalctl --user -u agent-guild.service`. `agent-guild status` prints
+the same state, read from systemd when no session manager answers.
+
 The browser tab icon adds a rotating green ring whenever any session card says
 **Working**, including Shell and task cards. It mirrors the cards' terminal
 activity, not assistant completion. The ring remains visible with reduced
@@ -255,7 +278,7 @@ There is no added polling while connected and no additional monitoring process.
 | Command | What it does |
 | --- | --- |
 | `agent-guild` or `agent-guild open` | Start the manager if needed and open the page. `--no-browser` prints the URL instead. |
-| `agent-guild status` | Show whether the manager is running and list its sessions. |
+| `agent-guild status` | Show whether the manager is running, how it starts, and list its sessions. |
 | `agent-guild stop` | Stop the manager, ending every session. |
 | `agent-guild restart` | Stop the manager and start it again on the version installed on disk, ending every session. |
 | `agent-guild url` | Print the page URL with its access token. |
@@ -337,12 +360,20 @@ Any other tool or script can report agents and its model too. See
   been uninstalled or moved removes itself at the next sign-in. With nvm,
   the package lives in the Node.js version's folder, so uninstalling that
   version counts as uninstalling Agent Guild; a Homebrew Node.js upgrade
-  does not. On macOS and Linux what the entry runs at sign-in, including a
+  or a Snap Node.js refresh does not. On macOS and Linux what the entry runs at sign-in, including a
   missing Node.js, is appended to `manager.log`.
   The entry saves the manager's listening port, including the assigned port
   when started with `AGENT_GUILD_PORT=0`. Enabled entries are updated when
   the manager starts. A macOS entry disabled through `launchctl` stays off
   until you explicitly turn **Launch at sign-in** back on.
+* **When the computer starts**, on Linux, writes
+  `~/.config/systemd/user/agent-guild.service` and enables it, which links
+  it from `default.target.wants`; the unit runs `boot.sh` from the data
+  folder, which runs `agent-guild start` in the foreground. Choosing another
+  option disables and removes both. A unit whose Agent Guild package has
+  been uninstalled or moved disables and removes itself at the next start.
+  Lingering, which lets it start before anyone signs in, is a system
+  setting that Agent Guild reads but never changes.
 
 The manager makes these outbound requests, and none of them carry your code
 or prompts:

package/bin/agent-guild.mjs

@@ -19,8 +19,9 @@ import {
   readRuntimeFile,
   resolvePort,
 } from '../src/manager/config.mjs';
-import { spawnManager } from '../src/manager/launch.mjs';
+import { defaultBoot, serviceFor, spawnManager, startService } from '../src/manager/launch.mjs';
 import { recordSignIn } from '../src/manager/autostart.mjs';
+import { EXIT_PORT_IN_USE, describeStartup, startupState, startupSummary, unitPort } from '../src/manager/systemd-service.mjs';
 
 function usage() {
   console.log(`Usage: agent-guild [command] [--no-browser]
@@ -105,6 +106,11 @@ async function ensureManager({ port = null } = {}) {
   const running = await health(knownUrl);
   if (running) return { url: knownUrl, started: false, version: running.version };
 
+  // While the boot service is on for this port, systemd is the one that starts a manager.
+  const { boot, note } = await serviceFor(listenPort);
+  if (boot) return startService({ boot, port: listenPort, url: expectedUrl, health });
+  if (note) console.log(note);
+
   const child = spawnManager({ env: { ...process.env, AGENT_GUILD_PORT: String(listenPort) } });
 
   let exited = false;
@@ -223,15 +229,26 @@ async function cmdStatus() {
   const h = await health(url);
   if (!h) {
     console.log('Session manager is not running.');
+    // With no manager to ask, the boot service is read from systemd directly.
+    const boot = defaultBoot();
+    const read = boot && await boot.read().catch(() => null);
+    if (read?.enabled) {
+      const port = unitPort(await boot.text().catch(() => null));
+      console.log(describeStartup(startupState(read.show, { port }), { linger: read.linger, user: boot.user }));
+    }
     process.exitCode = 3;
     return;
   }
-  const res = await fetch(`${url}/api/v1/sessions`, { headers: { Authorization: `Bearer ${loadOrCreateToken()}` } });
+  const headers = { Authorization: `Bearer ${loadOrCreateToken()}` };
+  const res = await fetch(`${url}/api/v1/sessions`, { headers });
   const { sessions = [] } = res.ok ? await res.json() : {};
   const running = sessions.filter((s) => s.status === 'running').length;
   console.log(`Session manager ${h.version} running at ${url} (pid ${h.pid}).`);
   const notice = versionNotice(h.version);
   if (notice) console.log(notice);
+  const startup = await fetch(`${url}/api/v1/autostart`, { headers }).then((r) => (r.ok ? r.json() : {}), () => ({}));
+  const summary = startupSummary(startup.autostart);
+  if (summary) console.log(summary);
   console.log(`${sessions.length} session(s), ${running} running.`);
   for (const s of sessions) {
     const model = s.model ? ` [${s.model.displayName || s.model.name}]` : '';
@@ -255,10 +272,19 @@ async function main() {
   switch (command) {
     case 'open': return cmdOpen({ browser: !flags.has('--no-browser'), signIn: flags.has('--sign-in') });
     case 'start': {
+      // `--service`: run by the Linux boot service, which systemd supervises.
+      const supervised = flags.has('--service');
       await import('../src/manager/main.mjs').then(async (m) => {
         process.on('uncaughtException', (err) => console.error('[manager] unexpected error:', err));
         process.on('unhandledRejection', (err) => console.error('[manager] unhandled rejection:', err));
-        const { shutdown } = await m.startManager();
+        const { shutdown } = await m.startManager({ supervised }).catch((err) => {
+          // Another manager has the port: an exit systemd does not retry, and the page reports.
+          if (supervised && err.code === 'EADDRINUSE') {
+            console.error(`agent-guild: ${err.message}`);
+            process.exit(EXIT_PORT_IN_USE);
+          }
+          throw err;
+        });
         console.log(`Open: ${pageUrl(readRuntimeFile()?.url ?? baseUrl(), loadOrCreateToken())}`);
         for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
           process.on(sig, () => shutdown(sig).then(() => process.exit(0)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "Launch and watch AI coding-assistant terminal sessions from one local web page. A bundled session manager owns the terminals so the page can close and reconnect.",
   "license": "MIT",
   "repository": {

package/src/manager/autostart.mjs

@@ -14,6 +14,10 @@
 //   runs a script in the data folder, as on macOS: desktops read Exec lines
 //   by different rules (systemd's autostart generator keeps a backslash that
 //   GLib removes), so the line holds only paths that read the same in all.
+//   Linux also offers a systemd user service that starts the manager when
+//   the computer starts (systemd-service.mjs). One starter at a time: the
+//   setting is a mode, off, sign-in or boot, and choosing one removes the
+//   other, so a sign-in never races the service for the port.
 //
 // Each launcher touches a file in the data folder before it starts Node.js,
 // and `open --sign-in` records whether a manager then answered, so the page
@@ -27,14 +31,15 @@
 // an entry whose package script is gone removes itself at sign-in instead
 // of failing there at every sign-in after. A missing Node.js alone keeps
 // the entry: the next manager to start points it at its own. Homebrew's
-// Node.js is named by its opt link, which an upgrade keeps, rather than by
-// the versioned Cellar folder the upgrade deletes.
+// and Snap's Node.js are named by the link an upgrade keeps (opt, current)
+// rather than by the versioned folder the upgrade deletes.
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { DEFAULT_PORT } from './config.mjs';
+import { BOOT_NOTE, UNIT_UNSAFE, bootSupported, createBootService, journalCommand, lingerCommand, startupState, systemdRunner, unitPort, userName } from './systemd-service.mjs';
 
 export const ARGS = ['open', '--no-browser', '--sign-in'];
 export const WINDOWS_RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
@@ -61,8 +66,8 @@ export const MAC_NOTE = 'Starts the session manager in the background when you s
 export const LINUX_NOTE = 'Starts the session manager in the background when you sign in to a desktop session on this computer. The page does not open. A computer with no desktop session, such as a server reached over SSH, does not start it. Desktop startup settings list it as Agent Guild.';
 /** Added to LINUX_NOTE when the manager itself was not started from a desktop session. */
 export const LINUX_NO_DESKTOP = 'This manager was not started from a desktop session, so this computer may not have one.';
-/** Characters that systemd's autostart generator and GLib read differently in an Exec line. */
-const EXEC_UNSAFE = /["`$\\]/;
+/** Linux startup modes. */
+export const MODES = ['off', 'sign-in', 'boot'];
 
 const failure = (message) => Object.assign(new Error(message), { status: 500, code: 'autostart_failed' });
 
@@ -138,19 +143,31 @@ export function posixCommand({ launcher, ...paths }) {
 }
 
 /**
- * Homebrew runs Node.js from `<prefix>/Cellar/<formula>/<version>`, which
- * the next upgrade deletes. `<prefix>/opt/<formula>` follows the formula
- * across upgrades, so it names Node.js instead when it leads to the same file.
+ * Versioned Node.js folders that an upgrade deletes, each with the link that
+ * follows the package across upgrades. Homebrew runs Node.js from
+ * `<prefix>/Cellar/<formula>/<version>`, kept as `<prefix>/opt/<formula>`.
+ * A snap runs it from `<snaps>/<snap>/<revision>`, where `<snaps>` is
+ * `/snap` or `/var/lib/snapd/snap`, kept as `<snaps>/<snap>/current`; snapd
+ * removes old revisions after a refresh.
  */
+const VERSIONED_NODE = [
+  [/^(.+)\/Cellar\/([^/]+)\/[^/]+\/bin\/node$/, (prefix, formula) => `${prefix}/opt/${formula}/bin/node`],
+  [/^(.*\/snap)\/([^/]+)\/x?\d+\/bin\/node$/, (snaps, snap) => `${snaps}/${snap}/current/bin/node`],
+];
+
+/** Names Node.js by the link that survives upgrades, when that link leads to the same file. */
 export function stableExecPath(execPath, realpath = fs.realpathSync) {
-  const match = execPath.match(/^(.+)\/Cellar\/([^/]+)\/[^/]+\/bin\/node$/);
-  if (!match) return execPath;
-  const opt = `${match[1]}/opt/${match[2]}/bin/node`;
-  try {
-    return realpath(opt) === realpath(execPath) ? opt : execPath;
-  } catch {
-    return execPath;
+  for (const [pattern, link] of VERSIONED_NODE) {
+    const match = execPath.match(pattern);
+    if (!match) continue;
+    const stable = link(...match.slice(1));
+    try {
+      return realpath(stable) === realpath(execPath) ? stable : execPath;
+    } catch {
+      return execPath;
+    }
   }
+  return execPath;
 }
 
 const xml = (value) => value.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
@@ -306,6 +323,9 @@ async function clearSignIns(dataDir) {
  * @param {string|null} [opts.unavailable]  a reason autostart cannot be offered, which turns it off here
  * @param {(args: string[]) => Promise<{ status: number, stdout: string, stderr: string }>} [opts.reg]  reg.exe, replaceable in tests
  * @param {(args: string[]) => Promise<{ status: number, stdout: string, stderr: string }>} [opts.launchctl]  launchctl, replaceable in tests
+ * @param {(command: string, args: string[]) => Promise<object>} [opts.systemd]  systemctl and journalctl on Linux, replaceable in tests
+ * @param {string} [opts.lingerDir]  where systemd records lingering users, replaceable in tests
+ * @param {number} [opts.pid]  this manager, which the service state compares with systemd's
  */
 export function createAutostart({
   platform = process.platform,
@@ -321,6 +341,10 @@ export function createAutostart({
   reg = runCommand(path.win32.join(env.SystemRoot || env.SYSTEMROOT || env.WINDIR || 'C:\\Windows', 'System32', 'reg.exe')),
   uid = process.getuid?.(),
   launchctl = runCommand('/bin/launchctl'),
+  user = userName(uid),
+  systemd = systemdRunner({ uid, env }),
+  lingerDir,
+  pid = process.pid,
 }) {
   const entryExecPath = platform === 'win32' ? execPath : stableExecPath(execPath);
   const attempt = path.join(dataDir, SIGN_IN_ATTEMPT);
@@ -328,6 +352,9 @@ export function createAutostart({
   let note = null;
   let unusable = null;
   let refreshError = null;
+  /** The systemd user service, on a Linux that can offer it. */
+  let boot = null;
+  let bootRefreshError = null;
   let queue = Promise.resolve();
   /** One change or check at a time, so two clicks cannot interleave their writes. */
   const serial = (fn) => {
@@ -412,13 +439,15 @@ export function createAutostart({
         await fs.promises.rm(launcher, { force: true });
       },
     };
-  } else if (platform === 'linux' && !(env.WSL_DISTRO_NAME || /microsoft|wsl/i.test(release))) {
+  } else if (bootSupported({ platform, env, release })) {
     const file = path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'autostart', 'agent-guild.desktop');
     const launcher = path.join(dataDir, LINUX_LAUNCHER);
-    const unsafe = [entryExecPath, script, file, launcher, log, attempt].find((p) => EXEC_UNSAFE.test(p));
+    const service = createBootService({ env, home, user, uid, dataDir, run: systemd, ...(lingerDir && { lingerDir }) });
+    const unsafe = [entryExecPath, script, file, launcher, log, attempt, ...service.paths].find((p) => UNIT_UNSAFE.test(p));
     if (unsafe) {
-      unusable = `Not available because this path holds a character (", \`, $ or \\) that desktops read differently in a startup entry: ${unsafe}`;
+      unusable = `Not available because this path holds a character (", \`, $, \\ or a line break) that desktops and systemd read differently in a startup entry: ${unsafe}`;
     } else {
+      boot = service;
       const desktop = env.XDG_CURRENT_DESKTOP || env.WAYLAND_DISPLAY || env.DISPLAY;
       note = desktop ? LINUX_NOTE : `${LINUX_NOTE} ${LINUX_NO_DESKTOP}`;
       target = {
@@ -443,10 +472,25 @@ export function createAutostart({
     : unavailable || unusable || (platform === 'linux' ? 'Not available in WSL. Start Agent Guild from Windows to launch it at sign-in.'
       : 'Not available on this operating system.');
 
+  const FAILED = new Set(['failed', 'port-in-use']);
+  /** The service's side of a Linux description: its state, and the commands that are the next step. */
+  const describeBoot = async () => {
+    const read = await boot.read();
+    const base = { note: BOOT_NOTE, user, linger: read.linger };
+    if (!read.reachable) return { ...base, available: false, enabled: false, reason: read.reason, state: null, commands: [] };
+    const state = startupState(read.show, { pid, port: unitPort(await boot.text()) });
+    const commands = [];
+    if (read.enabled && FAILED.has(state.kind)) commands.push(journalCommand());
+    if (read.enabled && !read.linger) commands.push(lingerCommand(user));
+    return { ...base, available: true, enabled: read.enabled, reason: read.enabled ? bootRefreshError : null, state, commands };
+  };
+  const modeOf = (signIn, bootOn) => (signIn && bootOn ? 'both' : bootOn ? 'boot' : signIn ? 'sign-in' : 'off');
+
   const describe = async () => {
     if (!target) return { available: false, enabled: false, reason };
     try {
       const enabled = await target.enabled();
+      const linux = boot ? await describeBoot() : null;
       return {
         available: true,
         enabled,
@@ -455,38 +499,90 @@ export function createAutostart({
         // An unreadable record never keeps the setting from being turned off.
         lastRun: enabled ? await lastSignIn(dataDir).catch(() => null) : null,
         log,
+        ...(linux && { mode: modeOf(enabled, linux.enabled), boot: linux }),
       };
     } catch (err) {
       return { available: false, enabled: false, reason: `Could not read the startup setting: ${err.message}` };
     }
   };
 
-  return {
-    describe: () => serial(describe),
-    /** Turns autostart on or off and resolves to the new description. */
-    set: (enabled) => serial(async () => {
-      if (!target) throw Object.assign(new Error(reason), { status: 409, code: 'autostart_unavailable' });
+  /**
+   * Makes `mode` the one starter. The new one is added and confirmed before
+   * the old one goes, and nothing here starts or stops a manager: a service
+   * takes over at the manager's next restart or the computer's next start.
+   */
+  const apply = async (mode) => {
+    const signedIn = await target.enabled().catch(() => false);
+    // A fresh start says it has not run yet rather than report an earlier time it was on.
+    if (mode !== 'sign-in' || !signedIn) await clearSignIns(dataDir);
+    if (mode === 'boot') {
+      const read = await boot.read();
+      if (!read.reachable) throw Object.assign(new Error(read.reason), { status: 409, code: 'autostart_unavailable' });
       try {
-        // A fresh start says it has not run yet rather than report an earlier time it was on.
-        if (!enabled || !(await target.enabled().catch(() => false))) await clearSignIns(dataDir);
-        await (enabled ? target.enable() : target.disable());
-        refreshError = null;
-        const state = await describe();
-        if (!state.available || state.enabled !== enabled) throw failure(state.reason || 'Could not verify the startup setting.');
-        return state;
+        await boot.write(command());
+        await boot.reload();
+        await boot.enable();
+        if (!(await boot.read()).enabled) throw failure('systemd did not enable the unit.');
       } catch (err) {
-        throw err.code === 'autostart_failed' ? err : failure(`Could not change the startup setting: ${err.message}`);
+        // Leave no half-made unit behind; the sign-in entry, if any, is still in place.
+        if (!read.enabled) await boot.remove().catch(() => {});
+        throw err;
       }
+      await target.disable();
+      return;
+    }
+    await (mode === 'sign-in' ? target.enable() : target.disable());
+    if (boot) await boot.remove();
+  };
+
+  /** Applies the mode `pick` resolves to, inside the queue, and checks the result against what the OS reports. */
+  const change = (pick) => serial(async () => {
+    if (!target) throw Object.assign(new Error(reason), { status: 409, code: 'autostart_unavailable' });
+    const mode = await pick();
+    if (mode === 'boot' && !boot) throw Object.assign(new Error('Starting when the computer starts is offered only on Linux with systemd.'), { status: 409, code: 'autostart_unavailable' });
+    try {
+      await apply(mode);
+      refreshError = null;
+      bootRefreshError = null;
+      const state = await describe();
+      const done = boot ? state.mode === mode : state.enabled === (mode === 'sign-in');
+      if (!state.available || !done) throw failure(state.reason || 'Could not verify the startup setting.');
+      return state;
+    } catch (err) {
+      throw err.code === 'autostart_failed' || err.code === 'autostart_unavailable' ? err : failure(`Could not change the startup setting: ${err.message}`);
+    }
+  });
+
+  return {
+    describe: () => serial(describe),
+    /**
+     * Turns the sign-in entry on or off and resolves to the new description.
+     * On Linux, on means the sign-in mode, and off keeps a service that is on.
+     */
+    set: (enabled) => change(async () => {
+      if (enabled) return 'sign-in';
+      return boot && ['boot', 'both'].includes((await describe()).mode) ? 'boot' : 'off';
     }),
-    /** Points an entry that is on at this manager's Node.js, package and port. */
+    /** Linux: makes `mode` (off, sign-in or boot) the one way the manager starts. Elsewhere boot is unavailable. */
+    setMode: (mode) => change(async () => mode),
+    /** Points what is on at this manager's Node.js, package and port. */
     refresh: () => serial(async () => {
+      let first = null;
       try {
         if (target && await target.enabled()) await target.write();
         refreshError = null;
       } catch (err) {
         refreshError = `Could not update the sign-in entry: ${err.message}`;
-        throw err;
+        first = err;
+      }
+      try {
+        if (boot && (await boot.read()).enabled && await boot.write(command())) await boot.reload();
+        bootRefreshError = null;
+      } catch (err) {
+        bootRefreshError = `Could not update the systemd unit: ${err.message}`;
+        first ??= err;
       }
+      if (first) throw first;
     }),
   };
 }

package/src/manager/command-resolver.mjs

@@ -55,13 +55,15 @@ function candidateGroups(command, env, platform) {
  * Resolve `command` to an absolute path, or return null when it is not
  * installed. Commands that already contain a path separator are checked as-is.
  * `isExecutable` is injectable so tests can simulate another platform.
+ * `onSkip` drops a candidate before that check, without touching the filesystem.
  */
 export function resolveCommand(command, env = process.env, platform = process.platform, {
   isExecutable = (file) => isExecutableFile(file, platform),
+  onSkip = () => false,
 } = {}) {
   if (!command) return null;
   for (const group of candidateGroups(command, env, platform)) {
-    const hit = group.find((c) => isExecutable(c));
+    const hit = group.find((candidate) => !onSkip(candidate) && isExecutable(candidate));
     if (hit) return hit;
   }
   return null;