groove-dev 0.27.207 → 0.27.209

package/node_modules/@groove-dev/daemon/src/routes/axom.js

@@ -122,6 +122,119 @@ export function registerAxomRoutes(app, daemon) {
     }
   });
 
+  // ── Runtimes — the one entity (plans/axom-runtime-flow-redesign.md) ─────
+  // The GUI reasons about runtimes only; endpoints/instances/ssh are backends.
+
+  app.get('/api/axom/runtimes', async (req, res) => {
+    res.json(await daemon.axomRuntimes.status());
+  });
+
+  app.post('/api/axom/runtimes', (req, res) => {
+    try {
+      const rt = daemon.axomRuntimes.add(req.body);
+      if (req.body?.activate) daemon.axomRuntimes.activate(rt.id);
+      daemon.audit.log('axom.runtime.add', { id: rt.id, control: rt.control });
+      res.json(rt);
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.patch('/api/axom/runtimes/:id', (req, res) => {
+    try {
+      res.json(daemon.axomRuntimes.update(req.params.id, req.body || {}));
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.delete('/api/axom/runtimes/:id', (req, res) => {
+    try {
+      daemon.axomRuntimes.remove(req.params.id);
+      daemon.audit.log('axom.runtime.remove', { id: req.params.id });
+      res.json({ ok: true });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  // Mono-Axom (§10): a hook is a fresh session on the ONE runtime — never a
+  // second process. Used by the agent selector, new tabs, and new chats alike.
+  // Chats are named hooks, persisted daemon-side so the list survives a
+  // refresh. Removing one HIDES it — the conversation is the user's memory and
+  // lives in the runtime's ledger; GROOVE tidying its list never destroys it.
+  app.get('/api/axom/chats', (req, res) => {
+    res.json({ chats: daemon.axomRuntimes.chats() });
+  });
+
+  app.patch('/api/axom/chats/:session', (req, res) => {
+    try {
+      res.json(daemon.axomRuntimes.renameChat(req.params.session, req.body?.label));
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.delete('/api/axom/chats/:session', (req, res) => {
+    try {
+      const result = daemon.axomRuntimes.hideChat(req.params.session);
+      daemon.audit.log('axom.chat.hide', { session: req.params.session });
+      res.json(result);
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/hook', async (req, res) => {
+    try {
+      const result = await daemon.axomRuntimes.hook(req.body?.runtimeId, {
+        session: req.body?.session,
+        label: req.body?.label,
+      });
+      daemon.audit.log('axom.hook', { runtime: result.runtimeId, session: result.session });
+      res.json(result);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/runtimes/:id/activate', (req, res) => {
+    try {
+      daemon.axomRuntimes.activate(req.params.id);
+      res.json({ ok: true, activeRuntimeId: req.params.id });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/runtimes/:id/start', async (req, res) => {
+    try {
+      const result = await daemon.axomRuntimes.startRuntime(req.params.id);
+      daemon.audit.log('axom.runtime.start', { id: req.params.id });
+      res.json(result);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/runtimes/:id/stop', async (req, res) => {
+    try {
+      const result = await daemon.axomRuntimes.stopRuntime(req.params.id, { force: !!req.body?.force });
+      daemon.audit.log('axom.runtime.stop', { id: req.params.id });
+      res.json(result);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/runtimes/:id/heal', async (req, res) => {
+    try {
+      res.json(await daemon.axomRuntimes.heal(req.params.id));
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
   // ── Remote runtime control over SSH (manual only, never automatic) ──────
 
   app.get('/api/axom/remote', async (req, res) => {

package/node_modules/@groove-dev/daemon/src/routes/watch.js

@@ -20,6 +20,17 @@ export function registerWatchRoutes(app, daemon) {
       if (!who) return res.status(404).json({ error: `Unknown agent: ${agent}` });
 
       const watch = daemon.watcher.create(who.id, { command, until, label, timeoutMs, intervalMs });
+      if (watch.reattached) {
+        return res.json({
+          ok: true,
+          watchId: watch.id,
+          reattached: true,
+          message: `That command is ALREADY RUNNING under watch ${watch.id} ("${watch.label}") — `
+            + 'this request re-attached to it instead of starting a second copy. '
+            + 'Do NOT launch it again by hand. You will be resumed with the result when it finishes; '
+            + 'you can end your turn now.',
+        });
+      }
       res.json({
         ok: true,
         watchId: watch.id,

package/node_modules/@groove-dev/daemon/src/watcher.js

@@ -59,6 +59,28 @@ export class Watcher {
     if (!command && !until) throw new Error('Provide either "command" (run it) or "until" (poll it)');
     if (command && until) throw new Error('Provide only one of "command" or "until"');
 
+    // Re-attach, never re-execute. A daemon restart resumes the agent mid-turn,
+    // so it re-issues the watch it thinks never completed — and a second copy of
+    // a long job (training, benchmark) launched against the same working dir
+    // corrupts the first one's output and competes for the GPU. If an identical
+    // command is still running for this agent, hand back the existing watch.
+    // This is the daemon-side equivalent of an flock, and it has to live here
+    // because the agent cannot know a duplicate already exists.
+    if (command) {
+      const dup = [...this.watches.values()].find(
+        (w) => w.status === 'active'
+          && w.mode === 'command'
+          && w.command === command
+          && (w.agentName === agent.name || w.agentId === agentId)
+          && this._jobAlive(w),
+      );
+      if (dup) {
+        this.daemon.audit?.log('watch.duplicate', { id: dup.id, agent: agentId, label: dup.label });
+        console.log(`[Groove:Watcher] Re-attached to running watch ${dup.id} instead of re-running: ${dup.label}`);
+        return { ...this._public(dup), reattached: true };
+      }
+    }
+
     const active = [...this.watches.values()].filter((w) => w.agentId === agentId && w.status === 'active');
     if (active.length >= MAX_WATCHES_PER_AGENT) {
       throw new Error(`You already have ${MAX_WATCHES_PER_AGENT} active watches — cancel one before adding another`);
@@ -118,11 +140,14 @@ export class Watcher {
     // Run the command in a SUBSHELL so its own `exit N` can't kill the wrapper
     // before the sentinel is written; tee output to a file, then atomically
     // publish the exit code so the poller never sees a half-written value.
+    // Append rather than truncate: if this script is ever run twice, `>` would
+    // erase the first run's record — exactly the evidence you need to work out
+    // what happened. Appending keeps both.
     const script = [
       '#!/bin/sh',
       '(',
       watch.command,
-      `) > ${shq(watch.outFile)} 2>&1`,
+      `) >> ${shq(watch.outFile)} 2>&1`,
       `echo $? > ${shq(watch.statusFile)}.tmp && mv ${shq(watch.statusFile)}.tmp ${shq(watch.statusFile)}`,
       '',
     ].join('\n');
@@ -143,6 +168,16 @@ export class Watcher {
     }
   }
 
+  // Is this watch's detached job still running? Signal 0 tests for existence
+  // without delivering anything. A finished job (sentinel present) is not alive
+  // even if the pid happens to have been recycled by another process.
+  _jobAlive(watch) {
+    if (watch.mode !== 'command') return false;
+    if (watch.statusFile && existsSync(watch.statusFile)) return false; // already exited
+    if (!watch.pid) return false;
+    try { process.kill(watch.pid, 0); return true; } catch { return false; }
+  }
+
   // One poll iteration — checks for completion (sentinel for command mode, the
   // `until` command for until mode) and wakes the agent when it's met.
   _tick(watch) {
@@ -257,6 +292,7 @@ export class Watcher {
     if (!Array.isArray(data)) return 0;
 
     let rearmed = 0;
+    let lost = 0;
     const now = Date.now();
     for (const w of data) {
       // Drop stale finished watches; keep recent ones for history.
@@ -268,10 +304,27 @@ export class Watcher {
       }
       const watch = { ...w, _poll: null, _deadline: null };
       this.watches.set(watch.id, watch);
+
+      // A command watch whose job is gone with no exit sentinel died while the
+      // daemon was down. Polling it would just burn until the timeout and then
+      // report "may still be running" — say what actually happened instead.
+      if (watch.mode === 'command' && watch.pid
+          && !existsSync(watch.statusFile || '') && !this._jobAlive(watch)) {
+        lost++;
+        this._wake(watch, {
+          outcome: 'error',
+          summary: `The job for "${watch.label}" is no longer running and never recorded an exit code — `
+            + 'it was lost while the daemon was down. Check its output before assuming it finished.',
+          output: tailFile(watch.outFile, OUTPUT_TAIL),
+        });
+        continue;
+      }
+
       this._arm(watch);
       rearmed++;
     }
-    if (rearmed > 0) console.log(`[Groove:Watcher] Restored ${rearmed} active watch(es) after restart`);
+    if (rearmed > 0) console.log(`[Groove:Watcher] Re-attached to ${rearmed} running watch(es) after restart`);
+    if (lost > 0) console.log(`[Groove:Watcher] ${lost} watch(es) lost their job while the daemon was down`);
     this._persist();
     return rearmed;
   }

package/node_modules/@groove-dev/daemon/test/axom-connector.test.js

@@ -34,6 +34,8 @@ class MockBridge {
     this.shutdowns = [];
     this.messages = [];
     this.sinceSeen = []; // ?since values observed on WS connects
+    this.epochsSeen = [];
+    this.epoch = 'epoch-A';
     this.sockets = new Set();
   }
 
@@ -50,8 +52,12 @@ class MockBridge {
         ws.on('close', () => this.sockets.delete(ws));
         const since = url.searchParams.get('since');
         this.sinceSeen.push(since);
+        this.epochsSeen.push(url.searchParams.get('epoch'));
+        // §16.4: hello first; a stale client epoch voids `since` (full replay).
+        ws.send(JSON.stringify({ kind: 'ws_hello', payload: { epoch: this.epoch, since_honored: url.searchParams.get('epoch') === this.epoch } }));
+        const staleEpoch = url.searchParams.get('epoch') && url.searchParams.get('epoch') !== this.epoch;
         // Ring replay: everything after `since`, then live.
-        const from = since ? parseInt(since.slice(3), 10) : 0;
+        const from = (since && !staleEpoch) ? parseInt(since.slice(3), 10) : 0;
         for (const e of session.events) {
           if (parseInt(e.id.slice(3), 10) > from) ws.send(JSON.stringify(e));
         }
@@ -435,6 +441,43 @@ describe('AxomConnector', () => {
     assert.equal(latest.data.endpoints[0].sessions[0].live, false);
   });
 
+  it('§16.4: a changed epoch resets the cursor — a runtime restart is replayed, never swallowed', async () => {
+    connect();
+    await waitFor(() => connector.status().endpoints[0]?.sessions[0]?.watching);
+    bridge.emit('s-test0001', envelope(1, 'pipeline_start'));
+    bridge.emit('s-test0001', envelope(2, 'thought'));
+    await waitFor(() => daemon.broadcasts.filter((b) => b.type === 'axom:event').length === 2);
+
+    // Runtime "restarts": new epoch, event ids reset to 1, fresh history.
+    bridge.epoch = 'epoch-B';
+    bridge.sessions['s-test0001'].events = [envelope(1, 'pipeline_start', { fresh: true }), envelope(2, 'narration', { text: 'post-restart' })];
+    bridge.sessions['s-test0001'].socket.terminate();
+
+    // Reconnect: our epoch-A + since goes up, hello says epoch-B → we reset
+    // and take the full replay. Without the reset, monotonic dedup would
+    // silently drop both replayed events (ids <= lastSeq).
+    await waitFor(() => daemon.broadcasts.some((b) => b.type === 'axom:session:reset'), 5000);
+    await waitFor(() => daemon.broadcasts.filter((b) => b.type === 'axom:event' && b.envelope.payload?.fresh).length === 1, 5000);
+    const s = connector.status().endpoints[0].sessions[0];
+    assert.equal(s.buffered, 2); // the ring holds ONLY post-restart history
+    assert.ok(bridge.epochsSeen.includes('epoch-A')); // we did present the old epoch
+  });
+
+  it('recheck collapses a stale connected state the moment the runtime is gone', async () => {
+    connect();
+    await waitFor(() => connector.status().endpoints[0]?.status === 'connected');
+    daemon.broadcasts.length = 0;
+
+    // Runtime dies (a deliberate stop); without recheck the endpoint would
+    // stay 'connected' until the next scheduled session poll failed.
+    await bridge.close();
+    connector.recheck('local');
+    await waitFor(() => connector.status().endpoints[0]?.status === 'error');
+    // The transition broadcast rode the recheck — the GUI card moves with
+    // the verb, not with a poll.
+    assert.ok(daemon.broadcasts.some((b) => b.type === 'axom:status'));
+  });
+
   it('reports an unreachable endpoint honestly and recovers by retry', async () => {
     const deadUrl = bridge.url;
     const port = Number(new URL(deadUrl).port);

package/node_modules/@groove-dev/daemon/test/axom-runtimes.test.js

@@ -0,0 +1,367 @@
+// GROOVE — Axom Runtime Model Tests
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// The model is exercised with faked backends: what matters here is that verbs
+// dispatch on control mode, states derive honestly, and migration folds the
+// legacy keys without forking anyone's ledger.
+
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { AxomRuntimes, validateRuntime } from '../src/axom-runtimes.js';
+
+function fakeDaemon() {
+  const calls = { remote: [], server: [], connector: [], nudges: [], rechecks: [] };
+  const broadcasts = [];
+  return {
+    calls,
+    broadcasts,
+    grooveDir: mkdtempSync(join(tmpdir(), 'groove-axrt-')),
+    config: { axom: {} },
+    broadcast(m) { broadcasts.push(m); },
+    audit: { log() {} },
+    axom: {
+      endpoints: new Map(),
+      configure(entries) { calls.connector.push(entries); },
+      nudge(name) { calls.nudges.push(name); },
+      recheck(name) { calls.rechecks.push(name); },
+    },
+    axomRemote: {
+      async status(cfg) { calls.remote.push(['status', cfg]); return fakeDaemon._remoteStatus || { running: false }; },
+      async start(cfg) { calls.remote.push(['start', cfg]); return { started: true }; },
+      async stop(o, cfg) { calls.remote.push(['stop', o, cfg]); return { stopped: true, via: 'shutdown' }; },
+      async ensureTunnel(cfg) { calls.remote.push(['tunnel', cfg]); return { tunneled: true }; },
+    },
+    axomServer: {
+      instances: [],
+      list() { return this.instances; },
+      async start(id, opts) { calls.server.push(['start', id, opts]); return { id, port: 8737, status: 'running' }; },
+      async stop(id) { calls.server.push(['stop', id]); },
+    },
+  };
+}
+
+const SSH_RT = {
+  id: 'spark', name: 'Spark', url: 'http://127.0.0.1:8737', control: 'ssh',
+  ssh: { host: 'spark.local', user: 'axom' },
+  launch: { command: 'cd /x && PYTHONPATH=model python3 -u -m axom.cli serve --cpu' },
+};
+
+describe('AxomRuntimes', () => {
+  let daemon, model;
+
+  beforeEach(() => {
+    daemon = fakeDaemon();
+    model = new AxomRuntimes(daemon);
+    // The real broadcastStatus probes runtime URLs; record the push instead so
+    // these tests stay hermetic. The genuine payload has its own test below.
+    model.broadcastStatus = async () => { daemon.broadcasts.push({ type: 'axom:runtimes' }); };
+  });
+
+  it('migrates the legacy endpoint+remote pair into one ssh runtime', () => {
+    daemon.config.axom = {
+      endpoints: [{ name: 'local', url: 'http://127.0.0.1:8737' }],
+      remote: { host: 'edgexpert-aaa6.local', user: 'axom', port: 8737, command: 'python3 -m axom.cli serve', logPath: '/x.log' },
+    };
+    assert.equal(model.migrate(), true);
+    const [rt] = model.list();
+    assert.equal(rt.control, 'ssh');
+    assert.equal(rt.url, 'http://127.0.0.1:8737');
+    assert.equal(rt.ssh.host, 'edgexpert-aaa6.local');
+    assert.equal(rt.launch.command, 'python3 -m axom.cli serve');
+    assert.equal(model.activeId(), rt.id);
+    assert.equal(model.migrate(), false); // idempotent
+  });
+
+  // Found in Ryan's live config: endpoints[] emptied by a disconnect, remote
+  // host still configured — the old rule dropped it and showed a first-run
+  // splash for a machine he had already set up.
+  it('migrates a configured remote host even with no endpoint entry beside it', () => {
+    daemon.config.axom = {
+      endpoints: [],
+      remote: { host: 'edgexpert-aaa6.local', user: 'axom', port: 8737, command: 'python3 -u -m axom.cli serve' },
+    };
+    model.migrate();
+    const [rt] = model.list();
+    assert.equal(rt.control, 'ssh');
+    assert.equal(rt.ssh.host, 'edgexpert-aaa6.local');
+    assert.equal(rt.url, 'http://127.0.0.1:8737');
+  });
+
+  it('retries a migration that produced nothing, but never re-derives a real one', () => {
+    // An earlier build wrote an empty runtimes[] and then early-returned
+    // forever on `Array.isArray` — the host stayed stranded across restarts.
+    daemon.config.axom = {
+      runtimes: [],
+      remote: { host: 'spark.local', user: 'axom', port: 8737 },
+    };
+    assert.equal(model.migrate(), true);
+    assert.equal(model.list().length, 1);
+    // Now it is marked done: a runtime the user removes must not resurrect.
+    assert.equal(model.migrate(), false);
+    model.remove('spark');
+    assert.equal(model.migrate(), false);
+    assert.equal(model.list().length, 0);
+  });
+
+  it('migrates a lone endpoint into a connect-only runtime', () => {
+    daemon.config.axom = { endpoints: [{ name: 'other', url: 'http://127.0.0.1:9999' }] };
+    model.migrate();
+    assert.equal(model.list()[0].control, 'none');
+  });
+
+  it('start dispatches by control: ssh starts remotely and heals the tunnel', async () => {
+    model.add(SSH_RT);
+    await model.startRuntime('spark');
+    const kinds = daemon.calls.remote.map((c) => c[0]);
+    assert.ok(kinds.includes('start'));
+    assert.ok(kinds.includes('tunnel')); // reachability follows lifecycle
+    const cfg = daemon.calls.remote.find((c) => c[0] === 'start')[1];
+    assert.equal(cfg.host, 'spark.local');
+    // Spec passed verbatim, with only the blessed env exported ahead of it.
+    assert.ok(cfg.command.endsWith(SSH_RT.launch.command));
+    assert.match(cfg.command, /^export AXOM_MAX_CTX='8192'; /);
+  });
+
+  // A spec must mean the same thing in every control mode. SSH previously
+  // honoured only `command`, so structured cwd/env vanished — the class of bug
+  // that boots a 2048-ctx runtime from a spec that asked for 8192.
+  it('composes launch cwd and env into the ssh command instead of dropping them', async () => {
+    model.add({
+      ...SSH_RT,
+      launch: {
+        command: 'python3 -u -m axom.cli serve --cpu',
+        cwd: '/home/axom/Desktop/Axom/axom-release',
+        env: { PYTHONPATH: 'model', AXOM_MAX_CTX: '8192' },
+      },
+    });
+    await model.startRuntime('spark');
+    const { command } = daemon.calls.remote.find((c) => c[0] === 'start')[1];
+    // export before cd: a `VAR=x` prefix would bind to `cd`, not the runtime.
+    assert.match(command, /export PYTHONPATH='model';/);
+    assert.match(command, /cd '\/home\/axom\/Desktop\/Axom\/axom-release' && python3/);
+    assert.match(command, /AXOM_MAX_CTX='8192'/);
+    assert.ok(command.endsWith('python3 -u -m axom.cli serve --cpu'));
+  });
+
+  it('rejects launch env that is not clean name/value pairs', () => {
+    assert.ok(validateRuntime({ ...SSH_RT, launch: { command: 'x', env: ['A=1'] } }));
+    assert.ok(validateRuntime({ ...SSH_RT, launch: { command: 'x', env: { 'BAD NAME': '1' } } }));
+    assert.ok(validateRuntime({ ...SSH_RT, launch: { command: 'x', env: { A: { nested: 1 } } } }));
+    assert.equal(validateRuntime({ ...SSH_RT, launch: { command: 'x', env: { AXOM_MAX_CTX: '8192' }, cwd: '/x' } }), null);
+  });
+
+  it('start dispatches by control: local spawns and adopts the resulting port as its URL', async () => {
+    model.add({ id: 'here', name: 'This machine', control: 'local', launch: { command: 'axom' }, dataDir: '/home/axom/axom-serve/data' });
+    await model.startRuntime('here');
+    const [, id, opts] = daemon.calls.server[0];
+    assert.equal(id, 'here');
+    assert.equal(opts.dataDir, '/home/axom/axom-serve/data'); // ADOPTS the ledger
+    assert.equal(model.get('here').url, 'http://127.0.0.1:8737');
+  });
+
+  it('refuses lifecycle verbs on connect-only runtimes with an honest message', async () => {
+    model.add({ id: 'theirs', name: 'Theirs', url: 'http://127.0.0.1:7000', control: 'none' });
+    await assert.rejects(() => model.startRuntime('theirs'), /not controlled by GROOVE/);
+    await assert.rejects(() => model.stopRuntime('theirs'), /not controlled by GROOVE/);
+    await assert.rejects(() => model.heal('theirs'), /only ssh runtimes/);
+  });
+
+  it('derives ssh states honestly: tunnel-down vs stopped vs host-unreachable', async () => {
+    model.add({ ...SSH_RT, url: 'http://127.0.0.1:1' }); // nothing listens on :1
+    fakeDaemon._remoteStatus = { running: true };
+    assert.equal((await model.state('spark')).state, 'unreachable'); // up on host, tunnel down
+    fakeDaemon._remoteStatus = { running: false };
+    assert.equal((await model.state('spark')).state, 'stopped');
+    fakeDaemon._remoteStatus = { running: null, error: 'no route to host' };
+    const s = await model.state('spark');
+    assert.equal(s.state, 'unreachable');
+    assert.match(s.detail, /no route/);
+    delete fakeDaemon._remoteStatus;
+  });
+
+  it('reports connected when the connector has the stream', async () => {
+    model.add(SSH_RT);
+    daemon.axom.endpoints.set('spark', { status: 'connected' });
+    assert.equal((await model.state('spark')).state, 'connected');
+  });
+
+  it('status exposes exactly the verbs each state supports', async () => {
+    model.add({ id: 'theirs', name: 'Theirs', url: 'http://127.0.0.1:1', control: 'none' });
+    const { runtimes } = await model.status();
+    const theirs = runtimes.find((r) => r.id === 'theirs');
+    assert.equal(theirs.canStart, false);
+    assert.equal(theirs.canStop, false);
+    assert.equal(theirs.canHeal, false);
+  });
+
+  // ── Mono-Axom (§10) ─────────────────────────────────────────────────────
+  // One Axom per machine; hooks are sessions, never processes.
+
+  it('a hook on a running runtime mints a session and starts nothing', async () => {
+    model.add(SSH_RT);
+    daemon.axom.endpoints.set('spark', { status: 'connected', sessions: new Map() });
+    const a = await model.hook('spark');
+    const b = await model.hook('spark');
+    assert.match(a.session, /^s-/);
+    assert.notEqual(a.session, b.session); // each hook is its own recency thread
+    assert.equal(a.launched, false);
+    assert.equal(daemon.calls.remote.filter((c) => c[0] === 'start').length, 0);
+  });
+
+  it('a hook launches from the blessed spec only when nothing is running', async () => {
+    model.add({ ...SSH_RT, url: 'http://127.0.0.1:1' });
+    fakeDaemon._remoteStatus = { running: false };
+    const h = await model.hook('spark');
+    delete fakeDaemon._remoteStatus;
+    assert.equal(h.launched, true);
+    assert.equal(daemon.calls.remote.filter((c) => c[0] === 'start').length, 1);
+    // The blessed env rides the launch — a 2048-ctx boot is the bug it prevents.
+    assert.match(daemon.calls.remote.find((c) => c[0] === 'start')[1].command, /AXOM_MAX_CTX='8192'/);
+  });
+
+  it('a hook that loses the lock race joins the winner instead of erroring', async () => {
+    model.add({ ...SSH_RT, url: 'http://127.0.0.1:1' });
+    let probes = 0;
+    fakeDaemon._remoteStatus = { running: false };
+    daemon.axomRemote.start = async () => { throw new Error('another instance holds the data-dir lock'); };
+    // The loser re-derives: by the time it asks again, the winner is up.
+    const realState = model.state.bind(model);
+    model.state = async (id) => (++probes >= 2 ? { state: 'connected', detail: null } : realState(id));
+    const h = await model.hook('spark');
+    delete fakeDaemon._remoteStatus;
+    assert.equal(h.launched, false);
+    assert.equal(h.wonBy, undefined); // hook() reports the session, not the race
+    assert.match(h.session, /^s-/);
+  });
+
+  it('a user-set env value beats the blessed default — GROOVE never edits a spec', async () => {
+    model.add({ ...SSH_RT, launch: { command: 'serve', env: { AXOM_MAX_CTX: '4096' } } });
+    await model.startRuntime('spark');
+    const { command } = daemon.calls.remote.find((c) => c[0] === 'start')[1];
+    assert.match(command, /AXOM_MAX_CTX='4096'/);
+    assert.doesNotMatch(command, /8192/);
+  });
+
+  it('reports the shared generation slot so concurrent hooks can queue honestly', async () => {
+    model.add(SSH_RT);
+    const sessions = new Map([
+      ['s-one', { id: 's-one', live: true }],
+      ['s-two', { id: 's-two', live: false }],
+    ]);
+    daemon.axom.endpoints.set('spark', { status: 'connected', sessions });
+    const { runtimes } = await model.status();
+    assert.equal(runtimes[0].generationBusy, true);
+    assert.equal(runtimes[0].generationHolder, 's-one');
+    sessions.get('s-one').live = false;
+    assert.equal(model.generation('spark').generationBusy, false);
+  });
+
+  it('refuses to hook a runtime on someone else\'s machine with an honest sentence', async () => {
+    model.add({ id: 'theirs', name: 'Theirs', url: 'http://127.0.0.1:1', control: 'none' });
+    await assert.rejects(() => model.hook('theirs'), /runs on another machine/);
+  });
+
+  // ── Chats — the persistent hook list ────────────────────────────────────
+
+  it('records every hook as a chat that survives a reload', async () => {
+    model.add(SSH_RT);
+    daemon.axom.endpoints.set('spark', { status: 'connected', sessions: new Map() });
+    const a = await model.hook('spark', { label: 'Research' });
+    await model.hook('spark');
+    assert.equal(a.label, 'Research');
+    assert.equal(model.chats().length, 2);
+    // A fresh model over the same config sees them — the list is daemon-side.
+    assert.equal(new AxomRuntimes(daemon).chats().length, 2);
+  });
+
+  it('deleting a chat hides it and never touches the conversation', async () => {
+    model.add(SSH_RT);
+    daemon.axom.endpoints.set('spark', { status: 'connected', sessions: new Map() });
+    const { session } = await model.hook('spark', { label: 'Scratch' });
+    const result = model.hideChat(session);
+    assert.equal(model.chats().length, 0);
+    assert.match(result.note, /remains in Axom's memory/);
+    // The row is REMEMBERED as hidden, so rejoining the same session — which
+    // the connector's /sessions poll will keep reporting — can't resurrect it.
+    await model.hook('spark', { session });
+    assert.equal(model.chats().length, 0);
+    assert.equal(model.getChat(session).hidden, true);
+  });
+
+  it('names the generation holder only when it is a chat we minted', async () => {
+    model.add(SSH_RT);
+    const sessions = new Map();
+    daemon.axom.endpoints.set('spark', { status: 'connected', sessions });
+    const { session } = await model.hook('spark', { label: 'Research' });
+    sessions.set(session, { id: session, live: true });
+    assert.equal(model.generation('spark').generationHolderLabel, 'Research');
+    // A session opened elsewhere (REPL, another client) gets no invented name.
+    sessions.clear();
+    sessions.set('s-foreign', { id: 's-foreign', live: true });
+    assert.equal(model.generation('spark').generationHolder, 's-foreign');
+    assert.equal(model.generation('spark').generationHolderLabel, null);
+  });
+
+  it('keeps the connector in sync with the runtime list', () => {
+    model.add(SSH_RT);
+    model.remove('spark');
+    const last = daemon.calls.connector.pop();
+    assert.deepEqual(last, []);
+  });
+
+  // Axom-UX flag 1: the GUI's runtime cards must move on events, not a poll.
+  it('pushes fresh runtime state on every mutation and lifecycle verb', async () => {
+    const seen = () => daemon.broadcasts.filter((b) => b.type === 'axom:runtimes').length;
+    model.add(SSH_RT);
+    assert.ok(seen() >= 1);
+    let n = seen();
+    model.update('spark', { name: 'Spark 2' });
+    assert.ok(seen() > n);
+    n = seen();
+    model.activate('spark');
+    assert.ok(seen() > n);
+    n = seen();
+    await model.startRuntime('spark');
+    assert.ok(seen() > n);
+    // Axom-UX flag 3: start pulls the connector in NOW — 'running' must not
+    // linger for a backoff cycle before becoming 'connected'.
+    assert.deepEqual(daemon.calls.nudges, ['spark']);
+    n = seen();
+    await model.stopRuntime('spark');
+    assert.ok(seen() > n);
+    // ...and stop re-probes so a stale 'connected' collapses with the verb.
+    assert.deepEqual(daemon.calls.rechecks, ['spark']);
+    n = seen();
+    model.remove('spark');
+    assert.ok(seen() > n);
+  });
+
+  it('broadcastStatus emits the full axom:runtimes payload', async () => {
+    const d = fakeDaemon();
+    const m = new AxomRuntimes(d);
+    m.add({ id: 'here', name: 'This machine', control: 'local' }); // no URL → no probe
+    const deadline = Date.now() + 2000;
+    while (!d.broadcasts.some((b) => b.type === 'axom:runtimes')) {
+      if (Date.now() > deadline) throw new Error('no axom:runtimes broadcast');
+      await new Promise((r) => setTimeout(r, 10));
+    }
+    const msg = d.broadcasts.find((b) => b.type === 'axom:runtimes');
+    assert.equal(msg.data.activeRuntimeId, 'here');
+    assert.equal(msg.data.runtimes[0].state, 'stopped');
+    assert.equal(msg.data.runtimes[0].canStart, true);
+  });
+});
+
+describe('validateRuntime', () => {
+  it('accepts the three shapes and rejects garbage', () => {
+    assert.equal(validateRuntime(SSH_RT), null);
+    assert.equal(validateRuntime({ id: 'x', name: 'X', control: 'local' }), null); // url comes from spawn
+    assert.equal(validateRuntime({ id: 'y', name: 'Y', url: 'http://127.0.0.1:1', control: 'none' }), null);
+    assert.ok(validateRuntime({ id: 'z', name: 'Z', control: 'teleport' }));
+    assert.ok(validateRuntime({ id: 'z', name: 'Z', control: 'none' })); // none requires url
+    assert.ok(validateRuntime({ id: 'z', name: 'Z', control: 'ssh', url: 'http://127.0.0.1:1', ssh: { host: 'h;rm', user: 'u' } }));
+  });
+});