@oddessentials/agent-guild 0.4.0 → 0.6.0

package/README.md

@@ -8,8 +8,9 @@ coding tool, and see at a glance which sessions and agents are working.
 
 * **Start sessions from provider cards.** Anthropic (Claude Code), OpenAI
   (Codex CLI), Google (Gemini CLI), xAI (Grok Build), and a plain shell.
-  **New** starts a fresh session; **Existing** resumes one of
-  the tool's own earlier sessions from its id. Providers whose tool is not
+  **New** starts a fresh session; **Existing** lists the tool's own earlier
+  sessions, read from where the tool keeps them, with their ids, and
+  resumes one in its own folder, or any session by id. Providers whose tool is not
   installed are shown greyed out with an **Install** button that runs
   `npm install -g` in a session you can watch, or with install instructions
   when the tool is not an npm package. Installed tools show their version
@@ -33,15 +34,17 @@ coding tool, and see at a glance which sessions and agents are working.
 * **Close the page any time.** A separate local session manager owns the
   terminals. Reopen the page and it reconnects to the same sessions with
   their screens intact, as long as the manager is still running. Sessions do
-  not survive a computer restart. **Stop manager** in the top bar stops the
-  manager and ends every session; it asks first while any session is still
-  running.
+  not survive a computer restart. **Restart manager** in the top bar ends
+  every session and starts a fresh manager, and the page reconnects to it by
+  itself; **Stop manager** ends every session and leaves the manager
+  stopped. Both ask first while any session is still running. The top bar
+  also shows the version you are running.
 * **Stay current.** When a newer Agent Guild is on npm, an **Upgrade**
   button appears in the top bar and runs `npm install -g` in a session you
-  can watch. Sessions keep running; stop the manager and run `agent-guild
-  open` to use the new version.
+  can watch. Sessions keep running; once they are done, **Restart to use
+  vX.Y.Z** in the top bar switches to the new version.
 * **Light or dark.** The page follows your system theme and the top-bar
-  toggle switches it. The guild artwork is the dark theme.
+  toggle switches it.
 
 ## Requirements
 
@@ -69,6 +72,7 @@ page stores it and then removes it from the address bar.
 | `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 stop` | Stop the manager. This ends every session, without asking. The page's **Stop manager** button does the same and asks first while sessions are running. |
+| `agent-guild restart` | Stop the manager and start it again, on the version installed on disk. This ends every session, without asking. The page's **Restart manager** button does the same and asks first while sessions are running. |
 | `agent-guild start` | Run the manager in the foreground, for debugging. |
 | `agent-guild url` | Print the page URL with its token. |
 
@@ -100,6 +104,7 @@ one platform under a `win32` or `darwin` key. See
 | `usage` | Where the usage meters come from: `"claude"`, `"codex"`, `"gemini"`, `{ "command", "args" }` for a program that prints `{ "windows": [{ "label", "usedPercent", "resetsAt" }] }`, or `null` for none. |
 | `modelPattern` | Regular expression that finds the model name on the tool's screen when the tool does not report it. |
 | `resumeArgs` | Arguments that resume the tool's own session, with `{id}` standing for the id, e.g. `["--resume", "{id}"]`. Without it the card has no **Existing** button. |
+| `history` | Where the list of earlier sessions comes from: `"claude"`, `"codex"`, `"gemini"`, `"grok"` (the tool's own session files under its home folder), `{ "command", "args" }` for a program that prints `{ "sessions": [{ "id", "title", "cwd", "startedAt", "updatedAt" }] }`, or `null` for none, in which case **Existing** asks for an id. |
 | `env` | Extra environment variables for the tool. |
 | `accounts` | Further sign-ins of the tool, each in its own home folder, e.g. `[{ "id": "work", "label": "Work", "dir": "~/.claude-work" }]`. Without `dir`, the folder is `accounts/<provider>/<account>` in the data folder. The card shows one chip per account with its own meters, and a session starts under the chip picked; the tool signs in from inside the first session, and its reporting hooks are copied into the folder on first use. An entry with id `default` renames the tool's own sign-in. Needs `homeVar`. |
 | `homeVar` | The environment variable that moves the tool's home folder, e.g. `CLAUDE_CONFIG_DIR`. Set for Claude Code, Codex CLI, Gemini CLI and Grok Build by default. |

package/bin/agent-guild-report.mjs

@@ -9,6 +9,7 @@
 //   agent-guild-report <agent-id> [--name N] [--status working|waiting|idle|done]
 //                      [--detail TEXT] [--kind KIND] [--remove]
 //   agent-guild-report --model NAME [--display-name TEXT]
+//   agent-guild-report --session ID          (the tool's own session id, for resuming it later)
 //   agent-guild-report --hook                (reads a hook event as JSON on stdin:
 //                                             Claude Code, Codex CLI, Gemini CLI, Grok Build)
 //   agent-guild-report --claude-statusline [--passthrough]
@@ -27,6 +28,7 @@ if (!inSession && env.AGENT_GUILD_SESSION_ID && !env.AGENT_GUILD_REPORT_TOKEN) {
 
 const USAGE = `Usage: agent-guild-report <agent-id> [--name N] [--status working|waiting|idle|done] [--detail TEXT] [--kind KIND] [--remove]
        agent-guild-report --model NAME [--display-name TEXT]
+       agent-guild-report --session ID                     (the tool's own session id)
        agent-guild-report --hook                           (reads a coding tool's hook event JSON from stdin)
        agent-guild-report --claude-statusline [--passthrough]  (reads Claude Code status line JSON from stdin)`;
 
@@ -60,7 +62,8 @@ function readStdin() {
 }
 
 async function send(report) {
-  const kind = report.agentId !== undefined || report.finishForeground === true ? 'agents' : 'model';
+  const kind = report.agentId !== undefined || report.finishForeground === true ? 'agents'
+    : report.toolSessionId !== undefined ? 'tool-session' : 'model';
   const url = `${env.AGENT_GUILD_URL}/api/v1/sessions/${env.AGENT_GUILD_SESSION_ID}/${kind}`;
   const res = await fetch(url, {
     method: 'POST',
@@ -115,6 +118,16 @@ async function main() {
     await send({ model: args.model, displayName: args['display-name'] });
     return;
   }
+  if (args.session !== undefined && args.positional.length === 0) {
+    if (!args.session) {
+      console.error('agent-guild-report: --session needs an id');
+      process.exitCode = 2;
+      return;
+    }
+    if (!inSession) return;
+    await send({ toolSessionId: args.session });
+    return;
+  }
   const agentId = args.positional[0];
   if (!agentId) {
     console.error('agent-guild-report: an agent id is required (see --help)');

package/bin/agent-guild.mjs

@@ -4,25 +4,21 @@
 //   agent-guild [open]     start the session manager if needed, open the page
 //   agent-guild start      run the session manager in the foreground
 //   agent-guild stop       stop the manager (ends all sessions)
+//   agent-guild restart    stop the manager and start it again (ends all sessions)
 //   agent-guild status     show whether the manager is running
 //   agent-guild url        print the page URL (includes the access token)
 
 import fs from 'node:fs';
-import path from 'node:path';
 import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 import {
   DEFAULT_HOST,
   VERSION,
-  ensureDataDir,
   loadOrCreateToken,
   paths,
   readRuntimeFile,
   resolvePort,
 } from '../src/manager/config.mjs';
-
-const here = path.dirname(fileURLToPath(import.meta.url));
-const managerEntry = path.resolve(here, '../src/manager/main.mjs');
+import { spawnManager } from '../src/manager/launch.mjs';
 
 function usage() {
   console.log(`Usage: agent-guild [command] [--no-browser]
@@ -31,6 +27,7 @@ Commands:
   open      Start the session manager if needed and open the web page (default)
   start     Run the session manager in the foreground
   stop      Stop the session manager and every session it owns
+  restart   Stop the session manager and start it again; ends every session
   status    Show whether the session manager is running
   url       Print the web page URL, including the access token
 
@@ -47,6 +44,12 @@ function baseUrl() {
   return `http://${DEFAULT_HOST}:${resolvePort()}`;
 }
 
+/** The port a URL names, including the one its scheme implies. */
+function portOf(url) {
+  const parsed = new URL(url);
+  return parsed.port ? Number(parsed.port) : parsed.protocol === 'https:' ? 443 : 80;
+}
+
 async function health(url, timeoutMs = 1000) {
   try {
     const res = await fetch(`${url}/api/v1/health`, { signal: AbortSignal.timeout(timeoutMs) });
@@ -88,36 +91,21 @@ function tailLog(lines = 15) {
   }
 }
 
-const MAX_LOG_BYTES = 5 * 1024 * 1024;
+/** Start a manager unless one answers. `port` pins the one to listen on; by default the configured one. */
+async function ensureManager({ port = null } = {}) {
+  const listenPort = port ?? resolvePort();
+  const expectedUrl = `http://${DEFAULT_HOST}:${listenPort}`;
+  // A pinned port is the endpoint to serve, so it is also the one to check;
+  // a manager found anywhere else is not the one asked for.
+  const knownUrl = port === null ? baseUrl() : expectedUrl;
+  const running = await health(knownUrl);
+  if (running) return { url: knownUrl, started: false, version: running.version };
 
-/** Keep one previous log so the file cannot grow without bound. */
-function rotateLog() {
-  try {
-    if (fs.statSync(paths.log).size > MAX_LOG_BYTES) fs.renameSync(paths.log, `${paths.log}.1`);
-  } catch { /* no log yet */ }
-}
-
-async function ensureManager() {
-  const running = await health(baseUrl());
-  if (running) return { url: baseUrl(), started: false, version: running.version };
-
-  ensureDataDir();
-  rotateLog();
-  const log = fs.openSync(paths.log, 'a');
-  fs.writeSync(log, `\n--- starting manager ${new Date().toISOString()} ---\n`);
-  const child = spawn(process.execPath, [managerEntry], {
-    detached: true,
-    stdio: ['ignore', log, log],
-    windowsHide: true,
-    env: process.env,
-  });
-  child.unref();
-  fs.closeSync(log);
+  const child = spawnManager({ env: { ...process.env, AGENT_GUILD_PORT: String(listenPort) } });
 
   let exited = false;
   child.once('exit', () => { exited = true; });
   const deadline = Date.now() + 20000;
-  const expectedUrl = `http://${DEFAULT_HOST}:${resolvePort()}`;
   while (Date.now() < deadline && !exited) {
     await new Promise((r) => setTimeout(r, 250));
     const url = readRuntimeFile()?.pid === child.pid ? readRuntimeFile().url : expectedUrl;
@@ -147,30 +135,80 @@ async function cmdOpen({ browser }) {
   }
 }
 
-async function cmdStop() {
-  const url = baseUrl();
-  if (!(await health(url))) {
-    console.log('Session manager is not running.');
-    return;
-  }
-  // `stop` is documented as ending every session, so it does not ask; the
-  // web page's Stop manager button is the one that confirms first.
+/**
+ * Ask a running manager to stop, or to stop and start again. Resolves to
+ * what it reported: the running session count, and whether it will start
+ * a successor itself (a manager from before restarts only stops).
+ */
+async function requestShutdown(url, { restart = false } = {}) {
+  // `stop` and `restart` are documented as ending every session, so they do
+  // not ask; the web page's buttons are the ones that confirm first.
   const res = await fetch(`${url}/api/v1/shutdown`, {
     method: 'POST',
     headers: { Authorization: `Bearer ${loadOrCreateToken()}`, 'Content-Type': 'application/json' },
-    body: JSON.stringify({ force: true }),
+    body: JSON.stringify(restart ? { force: true, restart: true } : { force: true }),
   });
-  if (!res.ok) throw new Error(`stop failed: HTTP ${res.status}`);
-  const { running = 0 } = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`${restart ? 'restart' : 'stop'} failed: HTTP ${res.status}`);
+  const body = await res.json().catch(() => ({}));
+  const running = body.running ?? 0;
   if (running > 0) console.log(`Ending ${running} running session(s).`);
-  for (let i = 0; i < 40; i++) {
+  return { running, restart: body.restart === true };
+}
+
+/** Resolves to true once nothing answers at `url`, false when it still does after `timeoutMs`. */
+async function waitForStop(url, timeoutMs = 6000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
     await new Promise((r) => setTimeout(r, 150));
-    if (!(await health(url, 300))) {
-      console.log('Session manager stopped.');
+    if (!(await health(url, 300))) return true;
+  }
+  return false;
+}
+
+async function cmdStop() {
+  const url = baseUrl();
+  if (!(await health(url))) {
+    console.log('Session manager is not running.');
+    return;
+  }
+  await requestShutdown(url);
+  console.log(await waitForStop(url) ? 'Session manager stopped.' : 'Stop requested; the manager is still shutting down.');
+}
+
+async function cmdRestart() {
+  const url = baseUrl();
+  const before = await health(url);
+  if (!before) {
+    // Nothing to stop: a restart of a stopped manager is a start.
+    const { url: started, version } = await ensureManager();
+    console.log(`Session manager was not running; started Agent Guild ${version} at ${started}.`);
+    return;
+  }
+  const { restart } = await requestShutdown(url, { restart: true });
+  if (!restart) {
+    // A manager from before restarts stops without starting a successor,
+    // which is the case right after an upgrade: start one here instead.
+    if (!(await waitForStop(url, 15000))) throw new Error('the session manager did not stop, so it could not be restarted.');
+    // On the port the old one served, which an ephemeral port setting would otherwise lose.
+    const { url: started, version } = await ensureManager({ port: portOf(url) });
+    const changed = version !== before.version ? `, now Agent Guild ${version} (was ${before.version})` : '';
+    console.log(`Session manager restarted at ${started}${changed}.`);
+    return;
+  }
+  // The old manager starts its successor from the package on disk once its
+  // sessions have ended and its port is free, then exits.
+  const deadline = Date.now() + 30000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 250));
+    const now = await health(url, 500);
+    if (now && now.pid !== before.pid) {
+      const changed = now.version !== before.version ? `, now Agent Guild ${now.version} (was ${before.version})` : '';
+      console.log(`Session manager restarted at ${url}${changed}.`);
       return;
     }
   }
-  console.log('Stop requested; the manager is still shutting down.');
+  const details = tailLog();
+  throw new Error(`the session manager did not come back after the restart.${details ? `\n\nRecent log (${paths.log}):\n${details}` : ''}`);
 }
 
 async function cmdStatus() {
@@ -222,6 +260,7 @@ async function main() {
       return undefined;
     }
     case 'stop': return cmdStop();
+    case 'restart': return cmdRestart();
     case 'status': return cmdStatus();
     case 'url': {
       console.log(pageUrl(baseUrl(), loadOrCreateToken()));

package/config/providers.default.json

@@ -8,6 +8,7 @@
       "package": "@anthropic-ai/claude-code",
       "versionArgs": ["--version"],
       "usage": "claude",
+      "history": "claude",
       "homeVar": "CLAUDE_CONFIG_DIR",
       "accountEnv": { "CLAUDE_SECURESTORAGE_CONFIG_DIR": "{dir}" },
       "hooks": { "path": "settings.json", "example": "claude-code-settings.json" },
@@ -44,6 +45,7 @@
       "package": "@openai/codex",
       "versionArgs": ["--version"],
       "usage": "codex",
+      "history": "codex",
       "homeVar": "CODEX_HOME",
       "hooks": { "path": "hooks.json", "example": "codex-hooks.json" },
       "modelPattern": "\\bgpt-\\d[a-z0-9.-]*",
@@ -77,6 +79,7 @@
       "package": "@google/gemini-cli",
       "versionArgs": ["--version"],
       "usage": "gemini",
+      "history": "gemini",
       "homeVar": "GEMINI_CLI_HOME",
       "accountEnv": { "GEMINI_FORCE_FILE_STORAGE": "true" },
       "hooks": { "path": ".gemini/settings.json", "example": "gemini-settings.json" },
@@ -100,6 +103,7 @@
       "command": "grok",
       "package": "@xai-official/grok",
       "versionArgs": ["--version"],
+      "history": "grok",
       "homeVar": "GROK_HOME",
       "hooks": { "path": "hooks/agent-guild.json", "example": "grok-hooks.json" },
       "modelPattern": "\\bgrok-(?:build|\\d)[a-z0-9.-]*",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.4.0",
+  "version": "0.6.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/changelog.mjs

@@ -0,0 +1,195 @@
+import { EventEmitter } from 'node:events';
+import { compareVersions } from './versions.mjs';
+import { FeedError, USER_AGENT, decodeEntities, failure, readBody, refusal, webUrl } from './news.mjs';
+
+const REPOSITORY = 'oddessentials/agent-guild';
+const RELEASES_URL = `https://github.com/${REPOSITORY}/releases`;
+const API_URL = `https://api.github.com/repos/${REPOSITORY}/releases?per_page=30`;
+const TTL_MS = 60 * 60 * 1000;
+const RETRY_MS = 10 * 60 * 1000;
+const MISSING_MS = 2 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 20000;
+const MAX_BYTES = 5 * 1024 * 1024;
+const MAX_CHANGES = 100;
+const MAX_NOTES = 20000;
+const MAX_LINE = 1000;
+const RELEASE_TAG = /^v?(\d+\.\d+\.\d+)$/;
+const VERSION_HEADING = /^v?\d+\.\d+\.\d+(?![\d.])/;
+const INSTALL_STEPS = /^install or update$/i;
+const COMMIT_LINK = /\s*\(\[[0-9a-f]{7,40}\]\([^)\s]*\)\)/gi;
+const INLINE = /\*\*(.+?)\*\*|`([^`]+)`|!\[[^\]]*\]\([^)]*\)|<(https?:\/\/[^>\s]+)>|\[([^\]]+)\]\(([^)\s]+)\)|<\/?[a-z][^>]*>/gi;
+
+const iso = (time) => (time ? new Date(time).toISOString() : null);
+
+function textRun(text, strong) {
+  return strong ? { text: decodeEntities(text), strong: true } : { text: decodeEntities(text) };
+}
+
+function inline(source, strong = false) {
+  const runs = [];
+  let at = 0;
+  for (const match of source.matchAll(INLINE)) {
+    if (match.index > at) runs.push(textRun(source.slice(at, match.index), strong));
+    const [, bold, code, autolink, label, href] = match;
+    if (bold !== undefined) {
+      runs.push(...inline(bold, true));
+    } else if (code !== undefined) {
+      runs.push({ ...(strong && { strong: true }), text: code, code: true });
+    } else if (autolink !== undefined || label !== undefined) {
+      const url = webUrl(autolink ?? href);
+      runs.push({ ...textRun(label ?? autolink, strong), ...(url && { url }) });
+    }
+    at = match.index + match[0].length;
+  }
+  if (at < source.length) runs.push(textRun(source.slice(at), strong));
+  return runs;
+}
+
+const sameStyle = (a, b) => !a.url && !b.url && Boolean(a.code) === Boolean(b.code) && Boolean(a.strong) === Boolean(b.strong);
+
+function tidy(runs) {
+  const tidied = [];
+  for (const run of runs) {
+    const text = run.text.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ');
+    if (!text) continue;
+    const last = tidied.at(-1);
+    if (last && sameStyle(last, run)) last.text += text;
+    else tidied.push({ ...run, text });
+  }
+  if (tidied.length) {
+    tidied[0].text = tidied[0].text.trimStart();
+    tidied.at(-1).text = tidied.at(-1).text.trimEnd();
+  }
+  return tidied.filter((run) => run.text);
+}
+
+function plain(source) {
+  return tidy(inline(source)).map((run) => run.text).join('');
+}
+
+export function parseNotes(markdown) {
+  const sections = [];
+  let section = null;
+  let change = null;
+  let skipping = false;
+  let fenced = false;
+  let count = 0;
+  for (const whole of String(markdown ?? '').slice(0, MAX_NOTES).replace(/<!--[\s\S]*?(?:-->|$)/g, '').split(/\r?\n/)) {
+    const line = whole.slice(0, MAX_LINE);
+    if (/^\s*(?:```|~~~)/.test(line)) {
+      fenced = !fenced;
+      change = null;
+      continue;
+    }
+    if (fenced) continue;
+    const heading = /^\s{0,3}#{1,6}\s+(.*?)(?:\s+#+)?\s*$/.exec(line);
+    if (heading) {
+      const title = plain(heading[1]);
+      change = null;
+      section = null;
+      skipping = INSTALL_STEPS.test(title);
+      if (title && !skipping && !VERSION_HEADING.test(title)) sections.push(section = { title, changes: [] });
+      continue;
+    }
+    if (skipping) continue;
+    if (/^\s*([-*_])(?:\s*\1){2,}\s*$/.test(line)) {
+      change = null;
+      continue;
+    }
+    const bullet = /^\s*(?:[-*+]|\d{1,9}[.)])\s+(.*)$/.exec(line);
+    const body = (bullet ? bullet[1] : line.replace(/^\s*(?:>\s?)+/, '')).trim();
+    if (!body) {
+      change = null;
+      continue;
+    }
+    const runs = tidy(inline(body.replace(COMMIT_LINK, '')));
+    if (runs.length === 0) continue;
+    if (!bullet && change) {
+      change.splice(0, change.length, ...tidy([...change, { text: ' ' }, ...runs]));
+      continue;
+    }
+    if (count === MAX_CHANGES) break;
+    if (!section) sections.push(section = { title: null, changes: [] });
+    section.changes.push(change = runs);
+    count++;
+  }
+  return sections.filter((s) => s.changes.length > 0);
+}
+
+export function parseReleases(json) {
+  const list = JSON.parse(json);
+  if (!Array.isArray(list)) throw new FeedError('sent no releases');
+  const releases = new Map();
+  for (const release of list) {
+    if (!release || typeof release !== 'object' || release.draft || release.prerelease) continue;
+    const tag = String(release.tag_name ?? '');
+    const version = RELEASE_TAG.exec(tag)?.[1];
+    if (!version || releases.has(version)) continue;
+    const published = Date.parse(release.published_at);
+    releases.set(version, {
+      version,
+      url: webUrl(String(release.html_url ?? '')) ?? `${RELEASES_URL}/tag/${encodeURIComponent(tag)}`,
+      publishedAt: Number.isFinite(published) ? new Date(published).toISOString() : null,
+      sections: parseNotes(typeof release.body === 'string' ? release.body : ''),
+    });
+  }
+  return [...releases.values()].sort((a, b) => compareVersions(b.version, a.version));
+}
+
+export class Changelog extends EventEmitter {
+  constructor({
+    latest = () => null, fetchImpl = fetch, url = API_URL,
+    ttlMs = TTL_MS, retryMs = RETRY_MS, missingMs = MISSING_MS, timeoutMs = FETCH_TIMEOUT_MS, maxBytes = MAX_BYTES,
+  } = {}) {
+    super();
+    this.latest = latest;
+    this.fetchImpl = fetchImpl;
+    this.url = url;
+    this.ttlMs = ttlMs;
+    this.retryMs = retryMs;
+    this.missingMs = missingMs;
+    this.timeoutMs = timeoutMs;
+    this.maxBytes = maxBytes;
+    this.releases = [];
+    this.etag = null;
+    this.checkedAt = 0;
+    this.okAt = 0;
+    this.error = null;
+    this.refreshing = null;
+  }
+
+  snapshot() {
+    this._refreshDue();
+    return { refreshing: Boolean(this.refreshing), okAt: iso(this.okAt), error: this.error, releases: this.releases };
+  }
+
+  _refreshDue() {
+    if (this.refreshing) return;
+    const latest = this.latest();
+    const missing = Boolean(latest) && !this.releases.some((release) => release.version === latest);
+    const wait = this.error ? this.retryMs : missing ? this.missingMs : this.ttlMs;
+    if (Date.now() - this.checkedAt < wait) return;
+    this.refreshing = this._refresh().finally(() => {
+      this.refreshing = null;
+      this.emit('updated');
+    });
+  }
+
+  async _refresh() {
+    this.checkedAt = Date.now();
+    try {
+      const headers = { 'User-Agent': USER_AGENT, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28' };
+      if (this.etag) headers['If-None-Match'] = this.etag;
+      const res = await this.fetchImpl(this.url, { headers, signal: AbortSignal.timeout(this.timeoutMs) });
+      if (res.status !== 304) {
+        if (!res.ok) throw new FeedError(refusal(res));
+        this.releases = parseReleases(await readBody(res, this.maxBytes));
+        this.etag = res.headers.get('etag');
+      }
+      this.error = null;
+      this.okAt = Date.now();
+    } catch (err) {
+      this.error = failure(err, this.timeoutMs);
+    }
+  }
+}

package/src/manager/launch.mjs

@@ -0,0 +1,64 @@
+// Starting a session manager as a detached background process. Shared by
+// the `agent-guild` CLI, which starts one when none is running, and by a
+// manager that restarts itself: both run the package on disk, so a restart
+// after an upgrade comes up on the new version.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { ensureDataDir, paths } from './config.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+/** The manager entry point, from the package files on disk. */
+export const MANAGER_ENTRY = path.join(here, 'main.mjs');
+/** The package root the manager runs from. */
+export const ROOT_DIR = path.resolve(here, '../..');
+
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+
+/** Keep one previous log so the file cannot grow without bound. */
+function rotateLog() {
+  try {
+    if (fs.statSync(paths.log).size > MAX_LOG_BYTES) fs.renameSync(paths.log, `${paths.log}.1`);
+  } catch { /* no log yet */ }
+}
+
+/**
+ * Start a manager that outlives this process, with its output appended to
+ * `manager.log`. Returns the child; the caller watches `/health` or the
+ * runtime file to learn when it is serving.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv, note?: string }} [opts]
+ */
+export function spawnManager({ env = process.env, note = 'starting manager' } = {}) {
+  ensureDataDir();
+  rotateLog();
+  const log = fs.openSync(paths.log, 'a');
+  fs.writeSync(log, `\n--- ${note} ${new Date().toISOString()} ---\n`);
+  const child = spawn(process.execPath, [MANAGER_ENTRY], {
+    detached: true,
+    stdio: ['ignore', log, log],
+    windowsHide: true,
+    env,
+  });
+  child.unref();
+  fs.closeSync(log);
+  return child;
+}
+
+/**
+ * The double-click launcher for this platform, when the package carries one
+ * (a checkout of the repository; the npm package does not include them).
+ * Null otherwise, so a page never names a file that is not there.
+ */
+export function launcherPath(platform = process.platform, rootDir = ROOT_DIR) {
+  const name = platform === 'win32' ? 'AgentGuild.cmd' : platform === 'darwin' ? 'AgentGuild.command' : null;
+  if (!name) return null;
+  const file = path.join(rootDir, 'launchers', name);
+  try {
+    return fs.statSync(file).isFile() ? file : null;
+  } catch {
+    return null;
+  }
+}