@oddessentials/agent-guild 1.31.0 → 1.33.0

package/bin/agent-guild.mjs

@@ -66,17 +66,25 @@ function portOf(url) {
   return parsed.port ? Number(parsed.port) : parsed.protocol === 'https:' ? 443 : 80;
 }
 
-async function health(url, timeoutMs = 1000) {
+/** The manager's health, `{ busy: pid }` when the manager its runtime file names for `url` runs but did not answer in time, or null. */
+async function reach(url, timeoutMs = 1000) {
+  const signal = AbortSignal.timeout(timeoutMs);
   try {
-    const res = await fetch(`${url}/api/v1/health`, { signal: AbortSignal.timeout(timeoutMs) });
+    const res = await fetch(`${url}/api/v1/health`, { signal });
     if (!res.ok) return null;
     const body = await res.json();
     return body?.name === 'agent-guild' ? body : null;
   } catch {
-    return null;
+    const owner = signal.aborted ? readRuntimeFile() : null;
+    return owner?.url === url && running(owner.pid) ? { busy: owner.pid } : null;
   }
 }
 
+async function health(url, timeoutMs = 1000) {
+  const found = await reach(url, timeoutMs);
+  return found?.busy ? null : found;
+}
+
 function pageUrl(url, token) {
   return `${url}/#token=${token}`;
 }
@@ -114,7 +122,7 @@ async function ensureManager({ port = null } = {}) {
   // 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 answering = await health(knownUrl);
+  const answering = await reach(knownUrl);
   if (answering) return { url: knownUrl, started: false, version: answering.version };
 
   // Say why no manager can run here rather than start one that fails.
@@ -167,21 +175,23 @@ async function cmdOpen({ browser, signIn = false }) {
  * 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(restart ? { force: true, restart: true } : { force: true }),
-  });
-  if (!res.ok) {
-    const { error } = await res.json().catch(() => ({}));
-    throw new Error(`${restart ? 'restart' : 'stop'} failed: ${error?.message ?? `HTTP ${res.status}`}`);
+  const signal = AbortSignal.timeout(5000);
+  try {
+    const res = await fetch(`${url}/api/v1/shutdown`, {
+      method: 'POST', signal,
+      headers: { Authorization: `Bearer ${loadOrCreateToken()}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(restart ? { force: true, restart: true } : { force: true }),
+    });
+    const body = await res.json().catch(() => ({}));
+    signal.throwIfAborted();
+    if (!res.ok) throw new Error(`${restart ? 'restart' : 'stop'} failed: ${body.error?.message ?? `HTTP ${res.status}`}`);
+    const running = body.running ?? 0;
+    if (running > 0) console.log(`Ending ${running} running session(s).`);
+    return { running, restart: body.restart === true };
+  } catch (err) {
+    if (signal.aborted) throw new Error(`the session manager did not answer the ${restart ? 'restart' : 'stop'} request within 5 seconds; its outcome could not be confirmed.`);
+    throw err;
   }
-  const body = await res.json().catch(() => ({}));
-  const running = body.running ?? 0;
-  if (running > 0) console.log(`Ending ${running} running session(s).`);
-  return { running, restart: body.restart === true };
 }
 
 function running(pid) {
@@ -209,13 +219,13 @@ async function waitForExit(pid, timeoutMs = 15000) {
 
 async function cmdStop() {
   const url = baseUrl();
-  const h = await health(url);
+  const h = await reach(url);
   if (!h) {
     console.log('Session manager is not running.');
     return;
   }
   await requestShutdown(url);
-  if (await waitForExit(h.pid)) {
+  if (await waitForExit(h.busy ?? h.pid)) {
     console.log('Session manager stopped.');
     return;
   }
@@ -225,13 +235,14 @@ async function cmdStop() {
 
 async function cmdRestart() {
   const url = baseUrl();
-  const before = await health(url);
-  if (!before) {
+  const found = await reach(url);
+  if (!found) {
     // 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 before = found.busy ? { pid: found.busy } : found;
   const { restart } = await requestShutdown(url, { restart: true });
   if (!restart) {
     // A manager from before restarts stops without starting a successor,
@@ -239,7 +250,7 @@ async function cmdRestart() {
     if (!(await waitForExit(before.pid))) 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})` : '';
+    const changed = before.version && version !== before.version ? `, now Agent Guild ${version} (was ${before.version})` : '';
     console.log(`Session manager restarted at ${started}${changed}.`);
     return;
   }
@@ -250,7 +261,7 @@ async function cmdRestart() {
     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})` : '';
+      const changed = before.version && now.version !== before.version ? `, now Agent Guild ${now.version} (was ${before.version})` : '';
       console.log(`Session manager restarted at ${url}${changed}.`);
       return;
     }
@@ -261,7 +272,12 @@ async function cmdRestart() {
 
 async function cmdStatus() {
   const url = baseUrl();
-  const h = await health(url);
+  const h = await reach(url);
+  if (h?.busy) {
+    console.log(`Session manager running at ${url} (pid ${h.busy}) did not answer in time.`);
+    process.exitCode = 1;
+    return;
+  }
   if (!h) {
     console.log('Session manager is not running.');
     // With no manager to ask, the boot service is read from systemd directly.
@@ -294,15 +310,21 @@ async function cmdStatus() {
 
 async function cmdFireworks() {
   const url = baseUrl();
-  if (!(await health(url))) {
+  if (!(await reach(url))) {
     console.log('Session manager is not running.');
     process.exitCode = 3;
     return;
   }
-  const res = await fetch(`${url}/api/v1/yard/fireworks`, { method: 'POST', headers: { Authorization: `Bearer ${loadOrCreateToken()}` } });
-  if (!res.ok) throw new Error(`the session manager answered ${res.status}.`);
-  const { pages } = await res.json();
-  console.log(pages ? `Fireworks sent to ${pages} open page(s); every Yard on show lights up.` : 'No page is open to see the fireworks.');
+  const signal = AbortSignal.timeout(5000);
+  try {
+    const res = await fetch(`${url}/api/v1/yard/fireworks`, { method: 'POST', signal, headers: { Authorization: `Bearer ${loadOrCreateToken()}` } });
+    if (!res.ok) throw new Error(`the session manager answered ${res.status}.`);
+    const { pages } = await res.json();
+    console.log(pages ? `Fireworks sent to ${pages} open page(s); every Yard on show lights up.` : 'No page is open to see the fireworks.');
+  } catch (err) {
+    if (signal.aborted) throw new Error('the session manager did not answer the fireworks request within 5 seconds; delivery could not be confirmed.');
+    throw err;
+  }
 }
 
 const MIN_NODE_MAJOR = 22;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "1.31.0",
+  "version": "1.33.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.",
   "mcpName": "ai.oddessentials/agent-guild",
   "license": "AGPL-3.0-only",

package/src/manager/command-resolver.mjs

@@ -184,17 +184,19 @@ export function npmSpawnSpec(npm, args, env = process.env, platform = process.pl
 function runInOwnGroup(file, args, { env, cwd, timeoutMs, input, maxBuffer, signal }) {
   return new Promise((resolve, reject) => {
     let child;
+    // Registered before the spawn: a signal that lands once the command runs must find it.
+    const end = () => killGroup(child?.pid);
+    const release = endWithProcess(end);
     try {
       child = spawn(file, args, { env, cwd, detached: true });
     } catch (err) {
+      release();
       return reject(Object.assign(err, { stdout: '', stderr: '' }));
     }
     let stdout = '';
     let stderr = '';
     let timedOut = false;
     let settled = false;
-    const end = () => killGroup(child.pid);
-    const release = endWithProcess(end);
     const finish = (err) => {
       if (settled) return;
       settled = true;

package/src/manager/session-hooks.mjs

@@ -214,6 +214,8 @@ export function codexHooksList(resolved, args, { env, platform = process.platfor
     const stopped = () => finish(new Error('The manager is stopping'));
     const timer = setTimeout(() => finish(new Error('Codex did not answer in time')), timeoutMs);
     timer.unref?.();
+    // Registered before the spawn: a signal that lands once Codex runs must find it.
+    if (platform !== 'win32') release = endWithProcess(() => killGroup(child?.pid));
     try {
       const verbatim = typeof spec.args === 'string';
       child = spawn(spec.file, verbatim ? [spec.args] : spec.args, {
@@ -222,7 +224,6 @@ export function codexHooksList(resolved, args, { env, platform = process.platfor
     } catch (err) {
       return finish(err);
     }
-    if (platform !== 'win32') release = endWithProcess(() => killGroup(child.pid));
     signal?.addEventListener('abort', stopped, { once: true });
     let stderr = '';
     let buffer = '';

package/src/manager/shell-env.mjs

@@ -78,6 +78,9 @@ export function probeLoginShell({ shell, env = process.env, timeoutMs = LOGIN_SH
   if (process.platform === 'win32' || !shell) return Promise.resolve({ vars: null, failure: null });
   return new Promise((resolve) => {
     let child;
+    // Registered before the spawn: a signal that lands once the shell runs must find it.
+    const end = () => killGroup(child?.pid);
+    const release = endWithProcess(end);
     try {
       child = spawn(shell, LOGIN_SHELL_ARGS, {
         detached: true,
@@ -85,12 +88,11 @@ export function probeLoginShell({ shell, env = process.env, timeoutMs = LOGIN_SH
         env: { ...env, AGENT_GUILD_RESOLVING_ENV: '1' },
       });
     } catch (err) {
+      release();
       return resolve({ vars: null, failure: `could not start (${err.code || err.message})` });
     }
     let stdout = '';
     let settled = false;
-    const end = () => killGroup(child.pid);
-    const release = endWithProcess(end);
     const finish = (result) => {
       if (settled) return;
       settled = true;

package/src/mcp/server.mjs

@@ -24,7 +24,7 @@ const HIDDEN = '[token hidden]';
 // 64 bits of the known token; leave colors, short hashes and 12-digit session ids readable.
 const MIN_TOKEN_FRAGMENT = 16;
 
-const CUSTOMIZE = 'To customize a Yard, or the characters and companions of Agent Guild: World, follow https://agentguild.oddessentials.ai/agents/.';
+const CUSTOMIZE = 'To customize a Yard or the characters and companions of Agent Guild: World, or to install Grove Companion on the desktop, follow https://agentguild.oddessentials.ai/agents/.';
 
 const INSTRUCTIONS = `Agent Guild runs coding agents (Claude Code, Codex CLI, Antigravity CLI, Grok Build, Docker Agent) and shells in real terminals on this computer, and opens them on every other screen.
 Use guild_status first, list_sessions to see the sessions, read_reply for the answer that ended a session's last turn, and read_screen for what its terminal shows now.

package/web/index.html

@@ -151,7 +151,7 @@
           <div class="yard-overlay">
             <div id="yard-loading" class="yard-loading" role="status" data-mode="scene"><span id="yard-loading-text">Preparing your yard…</span><span id="yard-loading-size" class="yard-loading-size" aria-hidden="true"></span><span class="yard-loading-bar" aria-hidden="true"></span></div>
             <div id="yard-swap-failure" class="yard-swap-failure" hidden role="status"><span id="yard-swap-failure-text"></span><button id="yard-swap-retry" class="btn" type="button">Retry</button></div>
-            <div class="yard-bar"><div id="yard-world" class="yard-world" role="group" aria-label="This Yard's world"><p id="yard-world-note" class="yard-world-note" role="status" hidden></p><div class="yard-world-actions"><button id="yard-customize-open" type="button" class="btn" aria-haspopup="dialog">Customize this Yard</button><a id="yard-world-get" class="btn" href="https://github.com/oddessentials/agent-guild-builders/releases/latest" target="_blank" rel="noopener noreferrer" hidden>Build a Yard</a></div></div><div class="yard-camera" role="group" aria-label="Yard controls"><button id="yard-zoom-in" type="button" class="btn" aria-label="Zoom in">+</button><button id="yard-zoom-out" type="button" class="btn" aria-label="Zoom out">−</button><button id="yard-fit" type="button" class="btn">Overview</button><button id="yard-focus" type="button" class="btn" disabled>Focus selected</button><button id="yard-photo" type="button" class="btn" aria-haspopup="dialog" aria-label="Save a picture of the Yard" title="Save a picture of the Yard" disabled hidden><svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M4 8.5A1.5 1.5 0 0 1 5.5 7h2.3l1.4-2h5.6l1.4 2h2.3A1.5 1.5 0 0 1 20 8.5v9a1.5 1.5 0 0 1-1.5 1.5h-13A1.5 1.5 0 0 1 4 17.5z"/><circle cx="12" cy="12.75" r="3.25"/></svg></button><button id="yard-fireworks" type="button" class="btn" aria-label="Fireworks in this Yard only" title="Fireworks in this Yard only" disabled><svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" aria-hidden="true" focusable="false"><path d="M12 3v3m0 9v6M3 10h3m12 0h3M5.6 3.6l2.2 2.2m8.4 8.4 2.2 2.2M18.4 3.6l-2.2 2.2m-8.4 8.4-2.2 2.2"/><circle cx="12" cy="10" r="1"/></svg></button></div></div>
+            <div class="yard-bar"><div id="yard-world" class="yard-world" role="group" aria-label="This Yard's world"><p id="yard-world-note" class="yard-world-note" role="status" hidden></p><div class="yard-world-actions"><button id="yard-customize-open" type="button" class="btn" aria-haspopup="dialog">Customize this Yard</button><a id="yard-world-get" class="btn" href="https://github.com/oddessentials/agent-guild-builders/releases/latest" target="_blank" rel="noopener noreferrer" hidden>Build a Yard</a></div></div><div class="yard-camera" role="group" aria-label="Yard controls"><button id="yard-zoom-in" type="button" class="btn" aria-label="Zoom in">+</button><button id="yard-zoom-out" type="button" class="btn" aria-label="Zoom out">−</button><button id="yard-fit" type="button" class="btn">Overview</button><button id="yard-focus" type="button" class="btn" disabled>Focus selected</button><button id="yard-photo" type="button" class="btn" aria-haspopup="dialog" aria-label="Save a picture of the Yard" title="Save a picture of the Yard" disabled hidden><svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M4 8.5A1.5 1.5 0 0 1 5.5 7h2.3l1.4-2h5.6l1.4 2h2.3A1.5 1.5 0 0 1 20 8.5v9a1.5 1.5 0 0 1-1.5 1.5h-13A1.5 1.5 0 0 1 4 17.5z"/><circle cx="12" cy="12.75" r="3.25"/></svg></button><button id="yard-fireworks" type="button" class="btn" aria-label="Fireworks in this Yard only" title="Fireworks in this Yard only" disabled><svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" aria-hidden="true" focusable="false"><path d="M12 3v3m0 9v6M3 10h3m12 0h3M5.6 3.6l2.2 2.2m8.4 8.4 2.2 2.2M18.4 3.6l-2.2 2.2m-8.4 8.4-2.2 2.2"/><circle cx="12" cy="10" r="1"/></svg></button><button id="yard-vibe" type="button" class="btn" aria-label="Vibes Mode" aria-pressed="false"><svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="14.5" cy="4.5" r="1.8"/><path d="M8 21l3.5-5.5-2.5-3 2.5-4.5 4 1.5 2 3h3"/><path d="M11.5 8 7.5 9.5 6 13"/><path d="M11 15.5l4 2V21"/></svg></button></div></div>
             <p id="yard-help"><span class="yard-help-pointer">Drag to explore · Scroll to zoom · Select to inspect · Double-click a session to open</span><span class="yard-help-touch">Drag to explore · Pinch to zoom · Tap to inspect · Open from the Inspector</span></p>
           </div>
         </div>