groove-dev 0.27.184 → 0.27.185

package/packages/daemon/src/innerchat.js

@@ -65,81 +65,127 @@ export class InnerChat {
       throw new Error(`${toAgent.name} is already answering another agent — try again shortly`);
     }
 
-    const thread = opts.threadId ? this.threads.get(opts.threadId) : this._findThread(fromAgentId, toAgentId);
-    const t = thread || this._createThread(fromAgent, toAgent);
+    const t = this._openThread(fromAgent, toAgent, opts.threadId);
+    this._checkExchangeCap(t, toAgent);
 
-    const exchanges = t.turns.filter((x) => x.kind === 'ask').length;
-    if (exchanges >= MAX_EXCHANGES) {
-      throw new Error(
-        `This conversation has reached its ${MAX_EXCHANGES}-exchange limit. Stop consulting `
-        + `${toAgent.name} and report your conclusion to the user.`,
-      );
+    const timeoutMs = Math.min(Number(opts.timeoutMs) || DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+
+    const { turn, targetId, skipResults } = await this._deliver(t, fromAgent, toAgent, message.trim(), 'ask');
+    this.daemon.audit.log('innerchat.ask', { thread: t.id, from: fromAgentId, to: targetId });
+
+    const reply = await this._awaitReply(t, fromAgentId, targetId, { skipResults, timeoutMs });
+    const exchanges = t.turns.filter((x) => x.kind === 'ask' || x.kind === 'tell').length;
+
+    return { reply, threadId: t.id, exchanges, remaining: MAX_EXCHANGES - exchanges };
+  }
+
+  /**
+   * Send a message to another agent WITHOUT blocking. Returns as soon as it's
+   * delivered. If the target later replies, the reply is routed back to the
+   * sender asynchronously — resuming the sender if its turn has ended.
+   *
+   * This is the fire-and-forget counterpart to ask(): use it to hand off to an
+   * agent that's heads-down, where waiting out a timeout would waste the turn.
+   */
+  async tell(fromAgentId, toAgentId, message, opts = {}) {
+    const fromAgent = this.daemon.registry.get(fromAgentId);
+    const toAgent = this.daemon.registry.get(toAgentId);
+    if (!fromAgent) throw new Error(`Calling agent ${fromAgentId} not found`);
+    if (!toAgent) throw new Error(`Target agent ${toAgentId} not found`);
+    if (fromAgentId === toAgentId) throw new Error('An agent cannot message itself');
+    if (!message || !message.trim()) throw new Error('message is required');
+    if (this.awaiting.has(toAgentId)) {
+      throw new Error(`${toAgent.name} already has an unanswered message — wait for its reply before sending another`);
     }
 
-    const timeoutMs = Math.min(Number(opts.timeoutMs) || DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    const t = this._openThread(fromAgent, toAgent, opts.threadId);
+    this._checkExchangeCap(t, toAgent);
 
+    const { turn, targetId, skipResults } = await this._deliver(t, fromAgent, toAgent, message.trim(), 'tell');
+    this.daemon.audit.log('innerchat.tell', { thread: t.id, from: fromAgentId, to: targetId });
+
+    // Register async capture: the reply (if any) is forwarded, not awaited.
+    this.awaiting.set(targetId, {
+      mode: 'async',
+      threadId: t.id,
+      senderId: fromAgentId,
+      skipResults,
+      timer: setTimeout(() => this._clearAwait(targetId), MAX_TIMEOUT_MS),
+    });
+
+    const exchanges = t.turns.filter((x) => x.kind === 'ask' || x.kind === 'tell').length;
+    return { delivered: true, threadId: t.id, exchanges, remaining: MAX_EXCHANGES - exchanges };
+  }
+
+  // Shared send: push a turn, deliver it, and remap the target id if delivery
+  // resumed/rotated the agent. Returns the queued-skip count for reply capture.
+  async _deliver(thread, fromAgent, toAgent, message, kind) {
     const turn = {
       id: randomUUID().slice(0, 12),
       from: peer(fromAgent),
       to: peer(toAgent),
-      text: message.trim(),
-      kind: 'ask',
+      text: message,
+      kind,
       status: 'sending',
       timestamp: Date.now(),
     };
-    t.turns.push(turn);
+    thread.turns.push(turn);
 
-    const wrapped = this._wrap(t, fromAgent, toAgent, message.trim());
+    const wrapped = this._wrap(thread, fromAgent, toAgent, message, kind);
 
     let result;
     try {
-      result = await deliverInstruction(this.daemon, toAgentId, wrapped, { recordFeedback: false });
+      result = await deliverInstruction(this.daemon, toAgent.id, wrapped, { recordFeedback: false });
     } catch (err) {
       turn.status = 'failed';
       turn.error = err.message;
-      t.status = 'failed';
-      this._broadcast(t, turn);
+      thread.status = 'failed';
+      this._broadcast(thread, turn);
       throw new Error(`Could not reach ${toAgent.name}: ${err.message}`);
     }
 
-    // A stopped target gets resumed or rotated, which mints a new agent id.
-    // Re-key onto it or the answer will never be matched.
+    // A stopped target gets resumed or rotated, minting a new agent id.
     const targetId = result.agentId;
-    if (targetId !== toAgentId) {
-      this._remapParticipant(t, toAgentId, targetId);
+    if (targetId !== toAgent.id) {
+      this._remapParticipant(thread, toAgent.id, targetId);
       turn.to.id = targetId;
     }
 
     turn.status = result.status;
-    t.status = 'awaiting_reply';
-    t.updatedAt = Date.now();
-    this._broadcast(t, turn);
-    this.daemon.audit.log('innerchat.ask', { thread: t.id, from: fromAgentId, to: targetId });
+    thread.status = 'awaiting_reply';
+    thread.updatedAt = Date.now();
+    this._broadcast(thread, turn);
 
-    // A queued question sits behind whatever the target is already doing, so
-    // the next result belongs to that prior task, not to us — skip it.
-    const skipResults = result.status === 'message_queued' ? 1 : 0;
+    // A queued message sits behind the target's current work, so the next
+    // result belongs to that prior task, not to us — skip it.
+    return { turn, targetId, skipResults: result.status === 'message_queued' ? 1 : 0 };
+  }
 
-    const reply = await this._awaitReply(t, fromAgentId, targetId, { skipResults, timeoutMs });
+  _openThread(fromAgent, toAgent, threadId) {
+    const thread = threadId ? this.threads.get(threadId) : this._findThread(fromAgent.id, toAgent.id);
+    return thread || this._createThread(fromAgent, toAgent);
+  }
 
-    return {
-      reply,
-      threadId: t.id,
-      exchanges: exchanges + 1,
-      remaining: MAX_EXCHANGES - (exchanges + 1),
-    };
+  _checkExchangeCap(thread, toAgent) {
+    const used = thread.turns.filter((x) => x.kind === 'ask' || x.kind === 'tell').length;
+    if (used >= MAX_EXCHANGES) {
+      throw new Error(
+        `This conversation has reached its ${MAX_EXCHANGES}-exchange limit. Stop consulting `
+        + `${toAgent.name} and report your conclusion to the user.`,
+      );
+    }
   }
 
   _awaitReply(thread, askerId, targetId, { skipResults, timeoutMs }) {
     return new Promise((resolve, reject) => {
       const settle = (fn, value) => {
-        clearTimeout(record.timer);
-        this.awaiting.delete(targetId);
+        this._clearAwait(targetId);
         this.blockedOn.delete(askerId);
         fn(value);
       };
 
       const record = {
+        mode: 'block',
         threadId: thread.id,
         askerId,
         skipResults,
@@ -150,7 +196,7 @@ export class InnerChat {
           thread.updatedAt = Date.now();
           record.reject(new Error(
             `No answer within ${Math.round(timeoutMs / 1000)}s. The agent may still be working — `
-            + 'proceed on your own judgement or try again.',
+            + 'proceed on your own judgement, or use a non-blocking send (tell) next time.',
           ));
         }, timeoutMs),
       };
@@ -161,7 +207,7 @@ export class InnerChat {
   }
 
   /**
-   * Watch agent output for the answer to an outstanding question.
+   * Watch agent output for the reply to an outstanding message.
    * Called from the process manager's output handler.
    */
   onAgentOutput(agentId, output) {
@@ -170,7 +216,7 @@ export class InnerChat {
     if (output.type !== 'result') return;
 
     const thread = this.threads.get(pending.threadId);
-    if (!thread) { pending.reject(new Error('Conversation was lost')); return; }
+    if (!thread) { this._settlePending(agentId, pending, null, new Error('Conversation was lost')); return; }
 
     const text = extractText(output.data);
     if (!text) return;
@@ -182,7 +228,7 @@ export class InnerChat {
     }
 
     const responder = this.daemon.registry.get(agentId);
-    thread.turns.push({
+    const answerTurn = {
       id: randomUUID().slice(0, 12),
       from: responder ? peer(responder) : { id: agentId, name: agentId, role: 'agent' },
       to: this._otherParticipant(thread, agentId),
@@ -190,27 +236,67 @@ export class InnerChat {
       kind: 'answer',
       status: 'delivered',
       timestamp: Date.now(),
-    });
+    };
+    thread.turns.push(answerTurn);
     thread.status = 'idle';
     thread.updatedAt = Date.now();
-
-    this._broadcast(thread, thread.turns.at(-1));
+    this._broadcast(thread, answerTurn);
     this.daemon.audit.log('innerchat.answer', { thread: thread.id, from: agentId });
 
-    pending.resolve(text);
+    if (pending.mode === 'async') {
+      this._clearAwait(agentId);
+      this._forwardAsyncReply(pending, answerTurn, text);
+    } else {
+      pending.resolve(text);
+    }
+  }
+
+  // Deliver an async (tell) reply back to the original sender, resuming it if
+  // its turn has ended. The sender is not blocked, so this just wakes them.
+  async _forwardAsyncReply(pending, answerTurn, text) {
+    const sender = this.daemon.registry.get(pending.senderId)
+      || this.daemon.registry.getAll().find((a) => a.name === answerTurn.to.name);
+    if (!sender) return; // sender is gone — nothing to route back to
+
+    const msg = [
+      `[InnerChat reply from ${answerTurn.from.name} (${answerTurn.from.role})]`,
+      '',
+      text,
+      '',
+      'This is a reply to a message you sent earlier (you were not blocking on it). '
+      + 'Fold it into your work, or reply again to continue.',
+    ].join('\n');
+
+    try {
+      await deliverInstruction(this.daemon, sender.id, msg, { recordFeedback: false });
+    } catch (err) {
+      this.daemon.audit.log('innerchat.forward_failed', { to: sender.id, error: err.message });
+    }
   }
 
   /**
-   * An agent that dies mid-question would otherwise leave its asker blocked
-   * until the timeout. Called when an agent crashes or is killed.
+   * An agent that dies mid-question would otherwise leave a blocking asker
+   * stuck until timeout. Async senders aren't waiting, so just clear those.
    */
   onAgentGone(agentId, reason = 'stopped') {
     const pending = this.awaiting.get(agentId);
     if (!pending) return;
+    if (pending.mode === 'async') { this._clearAwait(agentId); return; }
     const agent = this.daemon.registry.get(agentId);
     pending.reject(new Error(`${agent?.name || agentId} ${reason} before answering`));
   }
 
+  _clearAwait(targetId) {
+    const pending = this.awaiting.get(targetId);
+    if (pending?.timer) clearTimeout(pending.timer);
+    this.awaiting.delete(targetId);
+  }
+
+  _settlePending(agentId, pending, value, err) {
+    if (pending.mode === 'async') { this._clearAwait(agentId); return; }
+    if (err) pending.reject(err); else pending.resolve(value);
+  }
+
   // ── Threads ─────────────────────────────────────────────────
 
   _createThread(fromAgent, toAgent) {
@@ -233,10 +319,15 @@ export class InnerChat {
   }
 
   // The target sees a direct message from the other agent, with enough prior
-  // turns to follow a continuing conversation.
-  _wrap(thread, fromAgent, toAgent, message) {
+  // turns to follow a continuing conversation. The closing instruction differs
+  // by kind: an ask blocks the sender (answer now), a tell does not (answer
+  // when you reach a good stopping point).
+  _wrap(thread, fromAgent, toAgent, message, kind = 'ask') {
+    const header = kind === 'tell'
+      ? `[InnerChat — ${fromAgent.name} (${fromAgent.role}) sent you a message]`
+      : `[InnerChat — ${fromAgent.name} (${fromAgent.role}) is asking you a question]`;
     const prior = thread.turns.slice(0, -1).slice(-CONTEXT_TURNS);
-    const lines = [`[InnerChat — ${fromAgent.name} (${fromAgent.role}) is asking you a question]`, ''];
+    const lines = [header, ''];
 
     if (prior.length) {
       lines.push('Earlier in this conversation:');
@@ -245,11 +336,19 @@ export class InnerChat {
     }
 
     lines.push(message, '');
-    lines.push(
-      `${fromAgent.name} is BLOCKED waiting on your answer — it cannot continue until you `
-      + 'respond. Answer directly and concisely in your next message; that message is sent '
-      + 'back to it verbatim. Do not address the user, and do not start unrelated work first.',
-    );
+    if (kind === 'tell') {
+      lines.push(
+        `${fromAgent.name} is NOT blocked on this — finish what you're doing first if you're `
+        + 'mid-task. When you reach a good stopping point, answer directly in a message; your '
+        + `reply is relayed back to ${fromAgent.name}. If no reply is needed, just carry on.`,
+      );
+    } else {
+      lines.push(
+        `${fromAgent.name} is BLOCKED waiting on your answer — it cannot continue until you `
+        + 'respond. Answer directly and concisely in your next message; that message is sent '
+        + 'back to it verbatim. Do not address the user, and do not start unrelated work first.',
+      );
+    }
     return lines.join('\n');
   }
 
@@ -286,6 +385,20 @@ export class InnerChat {
     const pending = this.awaiting.get(agentId);
     return pending ? this.threads.get(pending.threadId) : null;
   }
+
+  // Clear all outstanding timers so a shutdown (or a test) doesn't hang on
+  // pending ask/tell timeouts. Blocking asks are rejected so their HTTP
+  // requests don't hang either.
+  stop() {
+    for (const [targetId, pending] of this.awaiting) {
+      if (pending.timer) clearTimeout(pending.timer);
+      if (pending.mode === 'block') {
+        try { pending.reject(new Error('Daemon shutting down')); } catch { /* already settled */ }
+      }
+      this.awaiting.delete(targetId);
+    }
+    this.blockedOn.clear();
+  }
 }
 
 function peer(agent) {

package/packages/daemon/src/introducer.js

@@ -4,7 +4,7 @@
 import { writeFileSync, readFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { resolve, dirname, basename } from 'path';
 import { escapeMd } from './validate.js';
-import { innerChatInstructions } from './innerchat-docs.js';
+import { innerChatInstructions, watchInstructions } from './innerchat-docs.js';
 
 const GROOVE_SECTION_START = '<!-- GROOVE:START -->';
 const GROOVE_SECTION_END = '<!-- GROOVE:END -->';
@@ -560,7 +560,8 @@ export class Introducer {
   // Written into every AGENTS_REGISTRY.md so the capability survives context
   // compaction — the spawn prompt alone can scroll out of a long session.
   _innerChatSection() {
-    return innerChatInstructions(this.daemon.port || 31415);
+    const port = this.daemon.port || 31415;
+    return [...innerChatInstructions(port), '', ...watchInstructions(port)];
   }
 
   writeRegistryFile(projectDir) {

package/packages/daemon/src/process.js

@@ -10,7 +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 } from './innerchat-docs.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');
@@ -562,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;
       }
     }
 
@@ -1165,11 +1170,15 @@ For normal file edits within your scope, proceed without review.
     // sandboxed providers (Codex) can't reach it.
     if (!sandboxedProviders.includes(providerName) && !isOneShotProvider) {
       const port = this.daemon.port || 31415;
-      const innerChatPrompt = innerChatInstructions(port, agent.name).join('\n') + '\n\n';
+      const capabilities = [
+        ...innerChatInstructions(port, agent.name),
+        '',
+        ...watchInstructions(port, agent.name),
+      ].join('\n') + '\n\n';
       if (spawnConfig.prompt.startsWith('# Handoff Brief')) {
-        spawnConfig.prompt += '\n\n' + innerChatPrompt.trim();
+        spawnConfig.prompt += '\n\n' + capabilities.trim();
       } else {
-        spawnConfig.prompt = innerChatPrompt + spawnConfig.prompt;
+        spawnConfig.prompt = capabilities + spawnConfig.prompt;
       }
     }
 

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

@@ -2,15 +2,51 @@
 
 import { MAX_EXCHANGES } from '../innerchat.js';
 
-// Agents know each other by name, not id — resolve either, preferring an
-// exact name match so `fullstack-1` never resolves to `fullstack-14`.
+// 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();
-  return all.find((a) => a.id === ref)
+  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() === ref.toLowerCase())
-    || null;
+    || 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) {
@@ -18,39 +54,25 @@ export function registerInnerChatRoutes(app, daemon) {
    * 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. That's what lets two
-   * agents iterate without a human relaying between them.
+   * 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, timeoutMs } = req.body || {};
-
-      const fromAgent = resolveAgent(daemon, from);
-      if (!fromAgent) return res.status(404).json({ error: `Unknown calling agent: ${from}` });
-
-      const toAgent = resolveAgent(daemon, to);
-      if (!toAgent) {
-        const names = daemon.registry.getAll()
-          .filter((a) => a.id !== fromAgent.id)
-          .map((a) => a.name);
-        return res.status(404).json({
-          error: `No agent named "${to}".`,
-          availableAgents: names,
-        });
-      }
-
-      if (!message || typeof message !== 'string' || !message.trim()) {
-        return res.status(400).json({ error: 'message is required' });
-      }
+      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(fromAgent.id, toAgent.id, message.trim(), { timeoutMs });
+      const result = await daemon.innerchat.ask(parties.fromAgent.id, parties.toAgent.id, parties.message, {
+        timeoutMs: req.body?.timeoutMs,
+      });
 
       res.json({
-        from: toAgent.name,
+        from: parties.toAgent.name,
         reply: result.reply,
         threadId: result.threadId,
         exchangesUsed: result.exchanges,
@@ -63,6 +85,36 @@ export function registerInnerChatRoutes(app, daemon) {
     }
   });
 
+  /**
+   * 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(409).json({ error: err.message });
+    }
+  });
+
   app.get('/api/innerchat/threads', (req, res) => {
     const { agentId } = req.query;
     res.json({ threads: daemon.innerchat.getThreads(agentId || null) });

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 });
+  });
+}