groove-dev 0.27.183 → 0.27.185

package/packages/daemon/src/introducer.js

@@ -4,6 +4,7 @@
 import { writeFileSync, readFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { resolve, dirname, basename } from 'path';
 import { escapeMd } from './validate.js';
+import { innerChatInstructions, watchInstructions } from './innerchat-docs.js';
 
 const GROOVE_SECTION_START = '<!-- GROOVE:START -->';
 const GROOVE_SECTION_END = '<!-- GROOVE:END -->';
@@ -556,6 +557,13 @@ export class Introducer {
     return null;
   }
 
+  // Written into every AGENTS_REGISTRY.md so the capability survives context
+  // compaction — the spawn prompt alone can scroll out of a long session.
+  _innerChatSection() {
+    const port = this.daemon.port || 31415;
+    return [...innerChatInstructions(port), '', ...watchInstructions(port)];
+  }
+
   writeRegistryFile(projectDir) {
     const agents = this.daemon.registry.getAll();
 
@@ -596,6 +604,27 @@ export class Introducer {
         lines.push(`| ${escapeMd(a.id)} | ${escapeMd(a.name)} | ${escapeMd(a.role)} | ${escapeMd(a.provider)} | ${agentDir} | ${scope} | ${escapeMd(a.status)} |`);
       }
 
+      // Agents on other teams are reachable via InnerChat, so they have to be
+      // discoverable here — otherwise cross-team consultation means guessing
+      // names. Kept to a separate, minimal table so the team's own roster
+      // stays the primary listing.
+      const others = agents.filter((a) => (a.teamId || '_default') !== teamId);
+      if (others.length > 0) {
+        lines.push('');
+        lines.push(`## Other Teams`);
+        lines.push('');
+        lines.push(`Reachable via InnerChat (see below). Not in your scope — do not edit their files.`);
+        lines.push('');
+        lines.push(`| Name | Role | Team | Status |`);
+        lines.push(`|------|------|------|--------|`);
+        for (const a of others) {
+          const otherTeam = this.daemon.teams?.get(a.teamId)?.name || '-';
+          lines.push(`| ${escapeMd(a.name)} | ${escapeMd(a.role)} | ${escapeMd(otherTeam)} | ${escapeMd(a.status)} |`);
+        }
+      }
+
+      lines.push('');
+      lines.push(...this._innerChatSection());
       lines.push('');
       lines.push(`*Updated: ${new Date().toISOString()}*`);
 
@@ -632,7 +661,8 @@ export class Introducer {
       running.length > 0 ? '|------|------|-------|' : '',
       ...running.map((a) => `| ${a.name} | ${a.role} | ${a.scope?.join(', ') || '-'} |`),
       '',
-      `See AGENTS_REGISTRY.md for full agent state.`,
+      `See AGENTS_REGISTRY.md for full agent state, the names of agents on other teams,`,
+      `and how to consult them directly (InnerChat).`,
       '',
       `**Memory policy:** GROOVE manages project memory automatically. Do not read or write MEMORY.md or .groove/memory/ files directly.`,
       '',

package/packages/daemon/src/process.js

@@ -10,6 +10,7 @@ import { LocalProvider } from './providers/local.js';
 import { OllamaProvider } from './providers/ollama.js';
 import { AgentLoop } from './agent-loop.js';
 import { validateAgentConfig } from './validate.js';
+import { innerChatInstructions, watchInstructions } from './innerchat-docs.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SLIDES_ENGINE_SRC = resolve(__dirname, '../templates/groove-slides.cjs');
@@ -506,6 +507,13 @@ export class ProcessManager {
 
     registry.update(agent.id, { status: finalStatus, pid: null });
 
+    // An agent that dies mid-question leaves its asker blocked on an open HTTP
+    // request — fail it now rather than making it wait out the timeout.
+    // 'completed' is normal: the answer arrives as a result before this fires.
+    if (this.daemon.innerchat && finalStatus !== 'completed') {
+      this.daemon.innerchat.onAgentGone(agent.id, finalStatus);
+    }
+
     if (this.daemon.timeline) {
       const agentData = registry.get(agent.id);
       this.daemon.timeline.recordEvent(finalStatus === 'completed' ? 'complete' : finalStatus === 'crashed' ? 'crash' : 'kill', {
@@ -554,12 +562,17 @@ export class ProcessManager {
       const pending = this.consumePendingMessage(agent.id);
       if (pending) {
         const agentData = registry.get(agent.id);
-        if (agentData?.sessionId) {
-          this.resume(agent.id, pending.message).catch((err) => {
-            console.error(`[Groove] Auto-resume with queued message failed for ${agent.name}: ${err.message}`);
-          });
-          return;
-        }
+        // Deliver the queued message: resume if there's a session, otherwise
+        // rotate (fresh session + handoff brief). Previously a missing sessionId
+        // meant the already-consumed message was silently dropped — an
+        // InnerChat message to a busy agent would vanish and never fire it.
+        const deliver = agentData?.sessionId
+          ? this.resume(agent.id, pending.message)
+          : this.daemon.rotator.rotate(agent.id, { additionalPrompt: pending.message });
+        deliver.catch((err) => {
+          console.error(`[Groove] Delivering queued message to ${agent.name} failed: ${err.message}`);
+        });
+        return;
       }
     }
 
@@ -1152,6 +1165,23 @@ For normal file edits within your scope, proceed without review.
       }
     }
 
+    // InnerChat — let the agent consult other agents directly.
+    // Same constraint as PM review: the agent calls back over HTTP, so
+    // sandboxed providers (Codex) can't reach it.
+    if (!sandboxedProviders.includes(providerName) && !isOneShotProvider) {
+      const port = this.daemon.port || 31415;
+      const capabilities = [
+        ...innerChatInstructions(port, agent.name),
+        '',
+        ...watchInstructions(port, agent.name),
+      ].join('\n') + '\n\n';
+      if (spawnConfig.prompt.startsWith('# Handoff Brief')) {
+        spawnConfig.prompt += '\n\n' + capabilities.trim();
+      } else {
+        spawnConfig.prompt = capabilities + spawnConfig.prompt;
+      }
+    }
+
     // Set up log capture (shared between CLI and agent loop paths)
     const logDir = resolve(this.daemon.grooveDir, 'logs');
     mkdirSync(logDir, { recursive: true });

package/packages/daemon/src/routes/innerchat.js

@@ -1,21 +1,117 @@
 // FSL-1.1-Apache-2.0 — see LICENSE
 
+import { MAX_EXCHANGES } from '../innerchat.js';
+
+// Agents know each other by name, not id. Exact matches win first so
+// `fullstack-1` never resolves to `fullstack-14`; only if nothing matches
+// exactly do we accept a single unambiguous partial, since agents routinely
+// half-remember a teammate's name. An ambiguous partial resolves to nothing
+// and the caller gets the candidate list instead of a wrong recipient.
+function resolveAgent(daemon, ref) {
+  if (!ref || typeof ref !== 'string') return null;
+  const all = daemon.registry.getAll();
+  const needle = ref.trim().toLowerCase();
+
+  const exact = all.find((a) => a.id === ref)
+    || all.find((a) => a.name === ref)
+    || all.find((a) => a.name.toLowerCase() === needle);
+  if (exact) return exact;
+
+  const partial = all.filter((a) => a.name.toLowerCase().includes(needle)
+    || needle.includes(a.name.toLowerCase()));
+  return partial.length === 1 ? partial[0] : null;
+}
+
+// Resolve the from/to pair from a request body, or write the appropriate
+// 400/404 and return null so the caller bails.
+function resolveParties(daemon, req, res) {
+  const { from, to, message } = req.body || {};
+
+  const fromAgent = resolveAgent(daemon, from);
+  if (!fromAgent) { res.status(404).json({ error: `Unknown calling agent: ${from}` }); return null; }
+
+  const toAgent = resolveAgent(daemon, to);
+  if (!toAgent) {
+    const others = daemon.registry.getAll().filter((a) => a.id !== fromAgent.id);
+    const needle = String(to || '').trim().toLowerCase();
+    const close = others.filter((a) => a.name.toLowerCase().includes(needle)).map((a) => a.name);
+    if (close.length > 1) {
+      res.status(404).json({ error: `"${to}" matches more than one agent — use the full name.`, didYouMean: close });
+    } else {
+      res.status(404).json({ error: `No agent named "${to}".`, availableAgents: others.map((a) => a.name) });
+    }
+    return null;
+  }
+
+  if (!message || typeof message !== 'string' || !message.trim()) {
+    res.status(400).json({ error: 'message is required' }); return null;
+  }
+  return { fromAgent, toAgent, message: message.trim() };
+}
+
 export function registerInnerChatRoutes(app, daemon) {
-  // Relay a message from one agent to another. Opens a thread, or continues
-  // an existing one when threadId is supplied.
-  app.post('/api/innerchat/send', async (req, res) => {
+  /**
+   * Ask another agent a question and BLOCK until it answers.
+   *
+   * This request is held open deliberately — the calling agent is waiting on
+   * it, and the response body is the other agent's reply. Best for tight
+   * interface negotiation, where the finite exchange budget keeps both sides
+   * writing decision-dense messages.
+   */
+  app.post('/api/innerchat/ask', async (req, res) => {
     try {
-      const { from, to, message, threadId } = req.body;
-      if (!from || typeof from !== 'string') return res.status(400).json({ error: 'from (agent ID) is required' });
-      if (!to || typeof to !== 'string') return res.status(400).json({ error: 'to (agent ID) is required' });
-      if (!message || typeof message !== 'string' || !message.trim()) return res.status(400).json({ error: 'message is required' });
-      if (from === to) return res.status(400).json({ error: 'cannot send a message to yourself' });
-      if (threadId && typeof threadId !== 'string') return res.status(400).json({ error: 'threadId must be a string' });
-
-      const result = await daemon.innerchat.send(from, to, message.trim(), threadId || null);
-      res.json(result);
+      const parties = resolveParties(daemon, req, res);
+      if (!parties) return;
+
+      // Held open until the target answers — see the class doc in innerchat.js.
+      req.setTimeout(0);
+      res.setTimeout(0);
+
+      const result = await daemon.innerchat.ask(parties.fromAgent.id, parties.toAgent.id, parties.message, {
+        timeoutMs: req.body?.timeoutMs,
+      });
+
+      res.json({
+        from: parties.toAgent.name,
+        reply: result.reply,
+        threadId: result.threadId,
+        exchangesUsed: result.exchanges,
+        exchangesRemaining: result.remaining,
+        maxExchanges: MAX_EXCHANGES,
+      });
+    } catch (err) {
+      // The agent reads this body — keep it actionable, it's the whole signal.
+      res.status(409).json({ error: err.message });
+    }
+  });
+
+  /**
+   * Send a message WITHOUT blocking — returns as soon as it's delivered. If the
+   * target replies, the reply is routed back to the sender asynchronously
+   * (resuming it if its turn ended). Best for handing off to a heads-down agent
+   * where waiting out a timeout would waste the turn.
+   */
+  app.post('/api/innerchat/tell', async (req, res) => {
+    try {
+      const parties = resolveParties(daemon, req, res);
+      if (!parties) return;
+
+      const result = await daemon.innerchat.tell(parties.fromAgent.id, parties.toAgent.id, parties.message, {
+        threadId: req.body?.threadId,
+      });
+
+      res.json({
+        ok: true,
+        to: parties.toAgent.name,
+        delivered: result.delivered,
+        threadId: result.threadId,
+        exchangesUsed: result.exchanges,
+        exchangesRemaining: result.remaining,
+        maxExchanges: MAX_EXCHANGES,
+        note: `Message delivered. ${parties.toAgent.name}'s reply, if any, will be routed back to you — you can end your turn.`,
+      });
     } catch (err) {
-      res.status(400).json({ error: err.message });
+      res.status(409).json({ error: err.message });
     }
   });
 

package/packages/daemon/src/routes/teams.js

@@ -26,6 +26,17 @@ export function registerTeamRoutes(app, daemon) {
     }
   });
 
+  // Reorder the sidebar list. Registered before /api/teams/:id so Express
+  // doesn't capture "reorder" as a team id.
+  app.post('/api/teams/reorder', (req, res) => {
+    try {
+      const teams = daemon.teams.reorder(req.body?.orderedIds);
+      res.json({ teams });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
   app.get('/api/teams/archived', (req, res) => {
     res.json({ archived: daemon.teams.listArchived() });
   });

package/packages/daemon/src/routes/watch.js

@@ -0,0 +1,42 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+// Agents identify themselves by name; resolve to the live record.
+function resolveAgent(daemon, ref) {
+  if (!ref || typeof ref !== 'string') return null;
+  const all = daemon.registry.getAll();
+  return all.find((a) => a.id === ref)
+    || all.find((a) => a.name === ref)
+    || all.find((a) => a.name.toLowerCase() === ref.trim().toLowerCase())
+    || null;
+}
+
+export function registerWatchRoutes(app, daemon) {
+  // Register a watch and return immediately — the agent's turn ends, and the
+  // wake comes later when the watched thing finishes. This does NOT block.
+  app.post('/api/watch', (req, res) => {
+    try {
+      const { agent, command, until, label, timeoutMs, intervalMs } = req.body || {};
+      const who = resolveAgent(daemon, agent);
+      if (!who) return res.status(404).json({ error: `Unknown agent: ${agent}` });
+
+      const watch = daemon.watcher.create(who.id, { command, until, label, timeoutMs, intervalMs });
+      res.json({
+        ok: true,
+        watchId: watch.id,
+        message: `Watching "${watch.label}". You'll be resumed with the result when it ${watch.mode === 'command' ? 'finishes' : 'condition is met'}. You can end your turn now.`,
+      });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.get('/api/watch', (req, res) => {
+    res.json({ watches: daemon.watcher.list(req.query.agentId || null) });
+  });
+
+  app.delete('/api/watch/:id', (req, res) => {
+    const ok = daemon.watcher.cancel(req.params.id);
+    if (!ok) return res.status(404).json({ error: 'Watch not found' });
+    res.json({ ok: true });
+  });
+}

package/packages/daemon/src/teams.js

@@ -113,6 +113,34 @@ export class Teams {
     return team;
   }
 
+  /**
+   * Reorder the team list. Teams persist as a JSON array, so Map insertion
+   * order is the display order — rebuilding the Map is the whole operation.
+   *
+   * Ids missing from `orderedIds` keep their relative order at the end, so a
+   * client working from a stale list can't drop teams.
+   */
+  reorder(orderedIds) {
+    if (!Array.isArray(orderedIds)) throw new Error('orderedIds must be an array');
+
+    const seen = new Set();
+    const next = new Map();
+    for (const id of orderedIds) {
+      const team = this.teams.get(id);
+      if (!team || seen.has(id)) continue;
+      seen.add(id);
+      next.set(id, team);
+    }
+    for (const [id, team] of this.teams) {
+      if (!seen.has(id)) next.set(id, team);
+    }
+
+    this.teams = next;
+    this._save();
+    this.daemon.broadcast({ type: 'teams:reordered', teams: this.list() });
+    return this.list();
+  }
+
   get(id) {
     return this.teams.get(id) || null;
   }

package/packages/daemon/src/watcher.js

@@ -0,0 +1,258 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import { deliverInstruction } from './deliver.js';
+
+// Watches are bounded so a wedged process or a condition that never comes true
+// can't poll forever or hold a slot indefinitely.
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+const MAX_TIMEOUT_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_POLL_MS = 15 * 1000;
+const MIN_POLL_MS = 3 * 1000;
+const MAX_WATCHES_PER_AGENT = 5;
+const OUTPUT_TAIL = 4000;
+
+/**
+ * Wake-on-completion for agents.
+ *
+ * An agent promises to "report back when the tests finish", but its process
+ * ends when the turn does — so nothing is left to report. A Watch lives in the
+ * daemon, not the agent's session: it outlives the turn, and when its target
+ * finishes it resumes the agent (from `completed` if need be, via the same
+ * pipe as user chat) with the outcome.
+ *
+ * Two flavours:
+ *   - command: the daemon runs a command detached and owns its lifecycle, so
+ *     it has the real exit code and output when it finishes.
+ *   - until:   the daemon polls a check command for something already running,
+ *     and wakes the agent when the check first succeeds (exit 0).
+ */
+export class Watcher {
+  constructor(daemon) {
+    this.daemon = daemon;
+    this.watches = new Map();
+  }
+
+  create(agentId, opts = {}) {
+    const agent = this.daemon.registry.get(agentId);
+    if (!agent) throw new Error('Agent not found');
+
+    const command = typeof opts.command === 'string' ? opts.command.trim() : '';
+    const until = typeof opts.until === 'string' ? opts.until.trim() : '';
+    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"');
+
+    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`);
+    }
+
+    const timeoutMs = Math.min(Number(opts.timeoutMs) || DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    const watch = {
+      id: randomUUID().slice(0, 12),
+      agentId,
+      agentName: agent.name,
+      label: (opts.label && String(opts.label).slice(0, 120)) || command || until,
+      mode: command ? 'command' : 'until',
+      command, until,
+      cwd: agent.workingDir || this.daemon.projectDir,
+      pollMs: Math.max(Number(opts.intervalMs) || DEFAULT_POLL_MS, MIN_POLL_MS),
+      timeoutMs,
+      status: 'active',
+      createdAt: Date.now(),
+      _child: null,
+      _poll: null,
+      _deadline: null,
+    };
+
+    this.watches.set(watch.id, watch);
+    watch._deadline = setTimeout(() => this._fireTimeout(watch), timeoutMs);
+    if (watch.mode === 'command') this._runCommand(watch);
+    else this._startPolling(watch);
+
+    this.daemon.audit?.log('watch.create', { id: watch.id, agent: agentId, mode: watch.mode });
+    this.daemon.broadcast?.({ type: 'watch:created', data: this._public(watch) });
+    return this._public(watch);
+  }
+
+  // ── command mode: daemon owns the process ─────────────────────
+
+  _runCommand(watch) {
+    const child = spawn('/bin/sh', ['-c', watch.command], {
+      cwd: watch.cwd,
+      env: process.env,
+      detached: false,
+    });
+    watch._child = child;
+
+    const chunks = [];
+    let bytes = 0;
+    const collect = (buf) => {
+      // Keep only the tail — a chatty build shouldn't grow this unbounded.
+      chunks.push(buf);
+      bytes += buf.length;
+      while (bytes > OUTPUT_TAIL * 2 && chunks.length > 1) bytes -= chunks.shift().length;
+    };
+    child.stdout?.on('data', collect);
+    child.stderr?.on('data', collect);
+
+    child.on('error', (err) => {
+      this._wake(watch, {
+        outcome: 'error',
+        summary: `Could not start the command: ${err.message}`,
+      });
+    });
+
+    child.on('close', (code, signal) => {
+      if (watch.status !== 'active') return; // already timed out / cancelled
+      const output = Buffer.concat(chunks).toString('utf8').slice(-OUTPUT_TAIL).trim();
+      this._wake(watch, {
+        outcome: code === 0 ? 'success' : 'failure',
+        exitCode: code,
+        signal,
+        summary: signal
+          ? `Terminated by signal ${signal}.`
+          : `Finished with exit code ${code}.`,
+        output,
+      });
+    });
+  }
+
+  // ── until mode: poll something already running ────────────────
+
+  _startPolling(watch) {
+    const tick = () => {
+      if (watch.status !== 'active') return;
+      const check = spawn('/bin/sh', ['-c', watch.until], { cwd: watch.cwd, env: process.env });
+      const chunks = [];
+      check.stdout?.on('data', (b) => chunks.push(b));
+      check.stderr?.on('data', (b) => chunks.push(b));
+      check.on('error', () => { /* transient — try again next tick */ });
+      check.on('close', (code) => {
+        if (watch.status !== 'active') return;
+        if (code === 0) {
+          const output = Buffer.concat(chunks).toString('utf8').slice(-OUTPUT_TAIL).trim();
+          this._wake(watch, { outcome: 'success', summary: 'Your watch condition is now true.', output });
+        }
+      });
+    };
+    watch._poll = setInterval(tick, watch.pollMs);
+    tick(); // check immediately — the condition may already hold
+  }
+
+  // ── firing ────────────────────────────────────────────────────
+
+  _fireTimeout(watch) {
+    if (watch.status !== 'active') return;
+    this._wake(watch, {
+      outcome: 'timeout',
+      summary: `Your watch "${watch.label}" hit its ${Math.round(watch.timeoutMs / 60000)}-minute time limit `
+        + 'without finishing. It may still be running — check on it directly.',
+    });
+  }
+
+  async _wake(watch, result) {
+    if (watch.status !== 'active') return;
+    watch.status = 'fired';
+    watch.firedAt = Date.now();
+    watch.result = result;
+    this._cleanup(watch);
+
+    const message = this._composeMessage(watch, result);
+
+    // Resolve by name, not the id we stored at creation: over a 30-minute
+    // watch the agent has very likely been chatted with and rotated to a new
+    // id. Names are stable across rotation, so this follows the agent; a
+    // purged/gone agent simply doesn't resolve and the watch is undeliverable
+    // rather than resurrecting a killed agent under a stale id.
+    const target = this.daemon.registry.getAll().find((a) => a.name === watch.agentName);
+    if (!target) {
+      watch.status = 'undeliverable';
+      watch.deliveryError = `Agent ${watch.agentName} no longer exists`;
+      this.daemon.audit?.log('watch.undeliverable', { id: watch.id, reason: 'agent gone' });
+      this.daemon.broadcast?.({ type: 'watch:fired', data: this._public(watch) });
+      return;
+    }
+
+    try {
+      const delivered = await deliverInstruction(this.daemon, target.id, message, { recordFeedback: false });
+      watch.agentId = delivered.agentId;
+      watch.status = 'delivered';
+    } catch (err) {
+      watch.status = 'undeliverable';
+      watch.deliveryError = err.message;
+      this.daemon.audit?.log('watch.undeliverable', { id: watch.id, error: err.message });
+    }
+
+    this.daemon.broadcast?.({ type: 'watch:fired', data: this._public(watch) });
+  }
+
+  _composeMessage(watch, result) {
+    const lines = [`[Watch fired — "${watch.label}"]`, '', result.summary];
+    if (result.output) {
+      lines.push('', 'Output (tail):', '```', result.output, '```');
+    }
+    lines.push('', 'This is the notification you set up earlier. Continue from here and report to the user.');
+    return lines.join('\n');
+  }
+
+  // ── lifecycle ─────────────────────────────────────────────────
+
+  cancel(id, agentId = null) {
+    const watch = this.watches.get(id);
+    if (!watch) return false;
+    if (agentId && watch.agentId !== agentId) return false;
+    if (watch.status === 'active') {
+      watch.status = 'cancelled';
+      this._cleanup(watch);
+      this.daemon.broadcast?.({ type: 'watch:cancelled', data: this._public(watch) });
+    }
+    return true;
+  }
+
+  // An agent that is killed/purged shouldn't leave watches firing into a void.
+  cancelForAgent(agentId) {
+    for (const watch of this.watches.values()) {
+      if (watch.agentId === agentId && watch.status === 'active') {
+        watch.status = 'cancelled';
+        this._cleanup(watch);
+      }
+    }
+  }
+
+  _cleanup(watch) {
+    if (watch._deadline) { clearTimeout(watch._deadline); watch._deadline = null; }
+    if (watch._poll) { clearInterval(watch._poll); watch._poll = null; }
+    if (watch._child && watch.mode === 'command' && watch.status === 'cancelled') {
+      // Only kill the process when the user/agent cancelled — a fired watch
+      // means it exited on its own.
+      try { watch._child.kill('SIGTERM'); } catch { /* already gone */ }
+    }
+    watch._child = null;
+  }
+
+  list(agentId = null) {
+    const all = [...this.watches.values()].sort((a, b) => b.createdAt - a.createdAt);
+    return (agentId ? all.filter((w) => w.agentId === agentId) : all).map((w) => this._public(w));
+  }
+
+  stop() {
+    for (const watch of this.watches.values()) {
+      if (watch._deadline) clearTimeout(watch._deadline);
+      if (watch._poll) clearInterval(watch._poll);
+      if (watch._child) { try { watch._child.kill('SIGTERM'); } catch { /* gone */ } }
+      watch._deadline = watch._poll = watch._child = null;
+    }
+  }
+
+  _public(w) {
+    return {
+      id: w.id, agentId: w.agentId, agentName: w.agentName, label: w.label,
+      mode: w.mode, command: w.command, until: w.until, status: w.status,
+      createdAt: w.createdAt, firedAt: w.firedAt || null, result: w.result || null,
+    };
+  }
+}
+
+export { DEFAULT_TIMEOUT_MS, MAX_WATCHES_PER_AGENT };