Start the daemon from whichever hook fires first

A plugin's SessionStart hook never runs, so nothing was starting the
daemon: no daemon.log, nothing on :8791, and a manual `glance up`
working perfectly.

Grok Build dispatches SessionStart from inside session creation
(xai-grok-shell, agent_ops.rs -> DispatchSessionStartHook) and resolves
it against the session's hook registry as it stands at that moment.
That registry comes from discover_hooks(), whose sources are the config
layers and the global/project settings files; plugin directories are not
among them. Plugin hooks are appended later, under a plugin/ prefix, by
reload_hooks_impl and reload_plugins_impl - which run in response to a
plugin action, a /hooks reload, or a folder-trust grant. So the entry is
always registered after the event it subscribes to has been dispatched.
The other thirteen events work because they happen later in the session.

There is no boot event to move to, so every recorder boots the daemon
instead and whichever fires first wins. The cost is one loopback request
to /healthz per event once it is up, which is the steady state. A
daemon.lock (O_EXCL, 15s staleness takeover) keeps a burst of concurrent
events from starting five daemons and leaving four to die on EADDRINUSE.

glance-up.mjs stays wired: it costs nothing when it does not fire, and
it is the right hook for the job if that ordering is ever fixed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

bin/glance

@@ -10,17 +10,16 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { spawn } from "node:child_process";
 import {
   PLUGIN_ROOT,
+  SERVER_ENTRY,
   baseUrl,
+  ensureDaemon,
   glanceHome,
   isDaemonUp,
   readConfig,
-  sleep,
 } from "./glance-lib.mjs";
 
-const SERVER_ENTRY = path.join(PLUGIN_ROOT, "dist", "server", "index.js");
 const cfg = readConfig();
 const cmd = process.argv[2] ?? "status";
 const args = process.argv.slice(3);
@@ -87,21 +86,10 @@ function requireBuild() {
 }
 
 async function ensureUp() {
-  if (await isDaemonUp(cfg)) return true;
   requireBuild();
-  const home = glanceHome();
-  fs.mkdirSync(home, { recursive: true });
-  const logFd = fs.openSync(path.join(home, "daemon.log"), "a");
-  const child = spawn(process.execPath, [SERVER_ENTRY], {
-    detached: true,
-    stdio: ["ignore", logFd, logFd],
-  });
-  child.unref();
-  for (let i = 0; i < 40; i++) {
-    await sleep(200);
-    if (await isDaemonUp(cfg, 300)) return true;
-  }
-  console.error(`daemon did not come up; see ${path.join(home, "daemon.log")}`);
+  // No hook timeout to fit inside here, so wait long enough that a slow cold start still counts.
+  if (await ensureDaemon(cfg, { waitMs: 8000, startedBy: "cli" })) return true;
+  console.error(`daemon did not come up; see ${path.join(glanceHome(), "daemon.log")}`);
   return false;
 }
 

bin/glance-lib.mjs

@@ -8,10 +8,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 export const PLUGIN_ROOT = path.resolve(fileURLToPath(import.meta.url), "../..");
 
+export const SERVER_ENTRY = path.join(PLUGIN_ROOT, "dist", "server", "index.js");
+
 export const DEFAULT_PORT = 8791;
 
 /**
@@ -140,3 +143,107 @@ export async function isDaemonUp(cfg = readConfig(), timeoutMs = 400) {
 }
 
 export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/* ------------------------------------------------------------------ daemon start */
+
+/**
+ * How long a spawn lock is believed before another hook takes it over. Long enough to cover a
+ * cold Node start and a bind, short enough that a script killed mid-spawn cannot wedge startup
+ * for the rest of the session.
+ */
+const SPAWN_LOCK_STALE_MS = 15_000;
+
+/** Never hold the lock for less than this, so a fire-and-forget caller still covers the bind. */
+const MIN_SPAWN_WAIT_MS = 600;
+
+/**
+ * Claim the right to spawn the daemon, so a burst of hooks does not start a race in which every
+ * loser dies on EADDRINUSE and litters daemon.log.
+ *
+ * `wx` is the whole mechanism: an atomic create-or-fail. A lock that is already there and still
+ * fresh means another script is mid-spawn, and we wait for its daemon rather than starting a
+ * second one. Taking over a *stale* lock is deliberately not atomic — two scripts could both
+ * decide it is stale and both spawn — because the consequence is only the EADDRINUSE we had
+ * before, and it takes a 15s-dead lock to get there at all.
+ */
+function acquireSpawnLock(home) {
+  const file = path.join(home, "daemon.lock");
+  try {
+    fs.writeFileSync(file, String(process.pid), { flag: "wx", mode: 0o600 });
+    return file;
+  } catch {
+    try {
+      if (Date.now() - fs.statSync(file).mtimeMs < SPAWN_LOCK_STALE_MS) return null;
+      fs.writeFileSync(file, String(process.pid), { mode: 0o600 });
+      return file;
+    } catch {
+      return null;
+    }
+  }
+}
+
+async function waitUntilUp(cfg, budgetMs) {
+  const deadline = Date.now() + budgetMs;
+  while (Date.now() < deadline) {
+    await sleep(100);
+    const left = deadline - Date.now();
+    if (left <= 0) break;
+    if (await isDaemonUp(cfg, Math.min(300, Math.max(50, left)))) return true;
+  }
+  return false;
+}
+
+/**
+ * Make sure the daemon is listening, starting it if it is not. Never throws.
+ *
+ * Every recording hook calls this, not just one designated boot hook, because Grok Build gives
+ * a plugin no usable boot event. `SessionStart` is dispatched from inside session creation
+ * (xai-grok-shell agent_ops.rs, `DispatchSessionStartHook`) and dispatch reads the session's
+ * hook registry as it stands at that moment. That registry is built by `discover_hooks()`,
+ * whose sources are the config layers and the global/project settings files — plugin hooks are
+ * not among them. They are appended later, with a `plugin/` prefix, only by `reload_hooks_impl`
+ * and `reload_plugins_impl`. So a plugin's `SessionStart` entry is registered strictly after
+ * `SessionStart` has already fired, and never runs. Every other event we subscribe to happens
+ * later in the session, once the plugin registry has landed — so whichever of them fires first
+ * is the one that has to boot us.
+ *
+ * The cost of asking is one loopback request to /healthz once the daemon is up, which is the
+ * steady state; the spawn path is taken once per machine boot.
+ */
+export async function ensureDaemon(cfg = readConfig(), options = {}) {
+  const { waitMs = 8000, startedBy = "hook", onMissingBuild } = options;
+  try {
+    if (await isDaemonUp(cfg)) return true;
+    if (!fs.existsSync(SERVER_ENTRY)) {
+      onMissingBuild?.(SERVER_ENTRY);
+      return false;
+    }
+    const home = glanceHome();
+    fs.mkdirSync(home, { recursive: true });
+
+    const budget = Math.max(waitMs, MIN_SPAWN_WAIT_MS);
+    const lock = acquireSpawnLock(home);
+    // Someone else is already starting it: wait on theirs instead of racing it.
+    if (!lock) return await waitUntilUp(cfg, budget);
+
+    try {
+      const logFd = fs.openSync(path.join(home, "daemon.log"), "a");
+      const child = spawn(process.execPath, [SERVER_ENTRY], {
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+        env: { ...process.env, GLANCE_STARTED_BY: startedBy },
+      });
+      child.unref();
+      return await waitUntilUp(cfg, budget);
+    } finally {
+      try {
+        fs.unlinkSync(lock);
+      } catch {
+        /* best effort */
+      }
+    }
+  } catch {
+    // A dashboard that cannot start must still not be the reason a tool call fails.
+    return false;
+  }
+}

bin/glance-record.mjs

@@ -11,11 +11,16 @@
  * A command hook costs a Node start (~40ms) per event, and buys back the ability to send an
  * authentication header, which the http runner has no config surface for.
  *
+ * It also boots the daemon if nothing else has. That is not this hook being greedy: a plugin's
+ * `SessionStart` entry provably never runs (see `ensureDaemon` in glance-lib.mjs), so there is
+ * no single boot event to delegate to and whichever recorder fires first has to do it.
+ *
  * Always exits 0. A dashboard must never be the reason a tool call fails.
  */
 
 import {
   baseUrl,
+  ensureDaemon,
   envEnvelope,
   hookHeaders,
   postJson,
@@ -23,11 +28,23 @@ import {
   readStdinJson,
 } from "./glance-lib.mjs";
 
+/**
+ * hooks/hooks.json gives this hook 5s. Everything below has to finish inside that with room to
+ * spare, because a killed script is a lost event either way — and losing one is fine, the next
+ * event is 40ms behind it.
+ */
+const START_BUDGET_MS = 1200;
+const POST_BUDGET_MS = 1500;
+
 try {
   const payload = envEnvelope(await readStdinJson());
   const cfg = readConfig();
-  // Short: if the daemon is not listening this must fail fast, not hold up the tool call.
-  await postJson(`${baseUrl(cfg)}/hook/record`, payload, 2000, hookHeaders());
+  // Cheap when the daemon is already up, which is every call but the first of the session.
+  if (await ensureDaemon(cfg, { waitMs: START_BUDGET_MS, startedBy: "record-hook" })) {
+    // hookHeaders() is read after the daemon is up: on a first-ever run it is the daemon we
+    // just started that created hook.secret.
+    await postJson(`${baseUrl(cfg)}/hook/record`, payload, POST_BUDGET_MS, hookHeaders());
+  }
 } catch {
   // Daemon down, no secret yet, malformed payload — all the same answer: carry on.
 }

bin/glance-up.mjs

@@ -2,64 +2,44 @@
 /**
  * SessionStart hook: make sure the glance daemon is running, then record the event.
  *
- * This is the only hook that spawns anything. It always exits 0 — a monitoring
- * dashboard must never be the reason a Grok Build session fails to start.
+ * Note that as of Grok Build's current hook wiring this never actually runs: a plugin's
+ * `SessionStart` entry is registered after `SessionStart` has already been dispatched, so the
+ * event finds no plugin hooks to call. `ensureDaemon` in glance-lib.mjs has the details, and
+ * bin/glance-record.mjs is what really boots the daemon.
+ *
+ * It stays wired anyway. It costs nothing when it does not fire, it is the correct hook for the
+ * job on the day that ordering is fixed, and it keeps the answer to "what starts this thing"
+ * in the obvious place.
+ *
+ * It always exits 0 — a monitoring dashboard must never be the reason a session fails to start.
  */
 
-import fs from "node:fs";
-import path from "node:path";
-import { spawn } from "node:child_process";
 import {
-  PLUGIN_ROOT,
   baseUrl,
+  ensureDaemon,
   envEnvelope,
-  glanceHome,
   hookHeaders,
-  isDaemonUp,
   postJson,
   readConfig,
   readStdinJson,
-  sleep,
 } from "./glance-lib.mjs";
 
-const SERVER_ENTRY = path.join(PLUGIN_ROOT, "dist", "server", "index.js");
-
-async function ensureDaemon(cfg) {
-  if (await isDaemonUp(cfg)) return true;
-
-  if (!fs.existsSync(SERVER_ENTRY)) {
-    // dist/ ships with the plugin, so this means an incomplete checkout. Say so once, on
-    // stderr, where it is recorded but harmless — a hook must never fail a session.
-    process.stderr.write(
-      `[grok-glance] dist/ is missing - run \`npm install && npm run build\` in ${PLUGIN_ROOT}\n`,
-    );
-    return false;
-  }
-
-  const home = glanceHome();
-  fs.mkdirSync(home, { recursive: true });
-  const logFd = fs.openSync(path.join(home, "daemon.log"), "a");
-
-  const child = spawn(process.execPath, [SERVER_ENTRY], {
-    detached: true,
-    stdio: ["ignore", logFd, logFd],
-    env: { ...process.env, GLANCE_STARTED_BY: "hook" },
-  });
-  child.unref();
-
-  // Give it a moment to bind before the first http hook fires.
-  for (let i = 0; i < 40; i++) {
-    await sleep(200);
-    if (await isDaemonUp(cfg, 300)) return true;
-  }
-  return false;
-}
-
 const payload = envEnvelope(await readStdinJson());
 const cfg = readConfig();
 
 try {
-  const up = await ensureDaemon(cfg);
+  // hooks/hooks.json allows this hook 20s; leave most of it as headroom.
+  const up = await ensureDaemon(cfg, {
+    waitMs: 8000,
+    startedBy: "session-start-hook",
+    onMissingBuild: (entry) => {
+      // dist/ ships with the plugin, so this means an incomplete checkout. Say so once, on
+      // stderr, where it is recorded but harmless — a hook must never fail a session.
+      process.stderr.write(
+        `[grok-glance] ${entry} is missing - run \`npm install && npm run build\` in the plugin root\n`,
+      );
+    },
+  });
   if (up) {
     // hookHeaders() is read here, not at import time: on a first-ever run the daemon we just
     // spawned is what created hook.secret.