@agentmessier/openclaw-agent-messier 0.3.8 → 0.3.10

package/index.ts

@@ -3,6 +3,7 @@ import { memberTools, venuesTool, agentIdOf, identityOf, venueUrl, type PluginCf
 import { defaultVenueTools, defaultRealtimeVenue, joinVenue } from "./src/generate.js";
 import { startObserveWatcher } from "./src/watcher.js";
 import { session } from "./src/state.js";
+import { runAutoplayTurn, STRICT_JSON_DIRECTIVE } from "./src/decide.js";
 
 /** A lobby row is "ours" if it references our agentId anywhere (soccer puts it in
  *  sides.home/away; a generic venue may shape it differently). Deep, shape-blind. */
@@ -83,17 +84,43 @@ export default function register(api: OpenClawPluginApi) {
               ctx.logger.warn(`[${label}] no sessionKey configured; cannot deliver move prompts.`);
               return;
             }
+            // Option A (docs/design/agent-bridge-plugin.md §2): force ONE agent
+            // turn per situation and PARSE its JSON reply — no longer wait for the
+            // agent to proactively call soccer_play (that reliance caused m171's
+            // 2-decisions-in-157s). soccer_play stays registered for interactive
+            // chat play; only AUTOPLAY changes to this server-driven loop.
+            //
             // Fresh session per move: each prompt is a complete snapshot, so the
             // agent needs no history — keeps context from overflowing.
             const turn = move++;
             const idempotencyKey = `agentnet:${venue.id}:${seat.id}:${agentId}:${turn}`;
-            const { runId } = await api.runtime.subagent.run({
+            // Mark when this prompt was handed to the agent: x-agent-decision-ms is
+            // the prompt→reply latency measured inside runAutoplayTurn.
+            session.promptDeliveredAt = Date.now();
+            const result = await runAutoplayTurn({
+              runtime: api.runtime,
               sessionKey: `${sessionKey}:${turn}`,
-              message: msg,
-              deliver: false,
               idempotencyKey,
+              // Steer the agent to reply with ONLY the moves JSON (no tool call).
+              message: `${msg}${STRICT_JSON_DIRECTIVE}`,
+              // 45s ceiling, matching the watcher's per-delivery watchdog backstop:
+              // a run that hasn't produced a decision by then is treated as stalled
+              // (was 300s, which let one hung run silence the team for 5 min — m171).
+              timeoutMs: 45_000,
+              matchId: seat.id!,
+              cfg,
+              did: session.did ?? agentId,
+              token: session.token,
+              base,
+              logger: ctx.logger,
             });
-            await api.runtime.subagent.waitForRun({ runId, timeoutMs: 300_000 });
+            // act-verification by the natural signal: did we parse+post (or did the
+            // model act via the tool)? A parse-miss = "responded without acting" —
+            // log, keep standing orders, continue (never freeze). The watcher's own
+            // lastActAt check stays correct because executeMoves/soccer_play stamp it.
+            if (!result.acted) {
+              ctx.logger.warn(`[${label}] agent responded without acting (turn ${turn}): ${result.reason}`);
+            }
           },
           {
             signal: controller.signal,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentmessier/openclaw-agent-messier",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Agent Messier multi-venue client for OpenClaw \u2014 play games and work tasks on the AgentNet platform (soccer today; venues discovered from the marketplace registry)",
   "type": "module",
   "license": "MIT",

package/src/decide.ts

@@ -0,0 +1,343 @@
+/**
+ * Option A decision-extraction — the server-driven decision core, ported from
+ * the tested prototype `services/soccer-driver/src/driver.ts` and adapted to run
+ * IN-PROCESS inside the customer's OpenClaw gateway.
+ *
+ * The m171 bug was relying on the agent to PROACTIVELY call the act tool: a
+ * model-dependent, unreliable behaviour that yielded 2 decisions in 157s. The
+ * fix (docs/design/agent-bridge-plugin.md §2) is request/response: per situation
+ * we FORCE one agent turn and PARSE its JSON reply — N situations → N decisions,
+ * regardless of tool-call discipline.
+ *
+ *   subagent.run({deliver:false}) → waitForRun → getSessionMessages
+ *        → lastAssistantText → parseMoves → POST /action per player
+ *
+ * Tool-vs-JSON-reply decision: the OpenClaw subagent API (SubagentRunParams) has
+ * NO knob to remove a tool from the run's scope, so the soccer act tool
+ * (soccer_play) is still in scope during an autoplay turn. We therefore (a) steer
+ * the prompt hard to "reply with ONLY the moves JSON, do NOT call any tool"
+ * (STRICT_JSON_DIRECTIVE), and (b) make the act path idempotent at the cycle
+ * level: if the model calls soccer_play anyway, that tool already POSTs actions
+ * and stamps session.lastActAt — so runAutoplayTurn detects that the team was
+ * acted (lastActAt advanced during the turn) and SKIPS the direct POST rather
+ * than double-applying. Only when the model replied with text (no tool call) do
+ * we parse that text and POST ourselves. Either way the cycle results in exactly
+ * one set of moves.
+ */
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import { apiKeyOf, type PluginCfg } from "./tools.js";
+import { session } from "./state.js";
+
+export type Vec2 = { x: number; y: number };
+
+export type Move = {
+  playerId: string;
+  type: string;
+  dir?: Vec2;
+  power?: number;
+  zone?: number;
+  say?: string;
+};
+
+/** Action vocabulary — mirrors services/pitch/src/schemas.ts `actionTypes`.
+ *  Kept local so the plugin carries no cross-package dependency. */
+export const ACTION_TYPES = [
+  "run", "kick", "idle", "chase", "shoot", "dribble",
+  "pass", "defend", "press", "cover", "push", "stop",
+] as const;
+
+export class DecideError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DecideError";
+  }
+}
+
+/** Appended to the autoplay move prompt so the agent replies with ONLY the moves
+ *  JSON instead of (or in addition to) calling the act tool. The strictness is
+ *  what keeps parseMoves reliable, and "do not call any tool" is what makes the
+ *  forced-turn-then-parse loop work regardless of the model's tool discipline. */
+export const STRICT_JSON_DIRECTIVE =
+  `\n\nDo NOT call any tool. Reply with ONLY a JSON object — no prose, no markdown ` +
+  `fences — in exactly this shape, one entry per player you control:\n` +
+  `{"moves":[{"playerId":"<id>","type":"<action>","dir":{"x":1,"y":0},"power":0.8,"zone":11,"say":"optional"}]}\n` +
+  `Valid action types: ${ACTION_TYPES.join(", ")}. ` +
+  `"run"/"kick" need dir {x,y}; "kick" also needs power 0..1; "push" needs zone 1..12; ` +
+  `"press"/"cover" may add zone 1..12. Omit fields an action does not need. Return the moves JSON now.`;
+
+// ── tolerant JSON extraction (ported from driver.ts) ─────────────────────────
+
+/** First balanced {…} or […] block, skipping string contents. */
+function firstBalanced(s: string): string | null {
+  const start = s.search(/[{[]/);
+  if (start < 0) return null;
+  const open = s[start];
+  const close = open === "{" ? "}" : "]";
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = start; i < s.length; i += 1) {
+    const c = s[i]!;
+    if (inStr) {
+      if (esc) esc = false;
+      else if (c === "\\") esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') inStr = true;
+    else if (c === open) depth += 1;
+    else if (c === close) {
+      depth -= 1;
+      if (depth === 0) return s.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+/** Parse JSON out of an LLM reply: whole body → ```json fence → first balanced
+ *  block. Returns null if nothing parses. */
+function extractJson(text: string): unknown {
+  const t = text.trim();
+  try {
+    return JSON.parse(t);
+  } catch {
+    /* fall through */
+  }
+  const fence = t.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fence?.[1]) {
+    try {
+      return JSON.parse(fence[1].trim());
+    } catch {
+      /* fall through */
+    }
+  }
+  const cand = firstBalanced(t);
+  if (cand) {
+    try {
+      return JSON.parse(cand);
+    } catch {
+      /* fall through */
+    }
+  }
+  return null;
+}
+
+function coerceDir(d: unknown): Vec2 | undefined {
+  if (d && typeof d === "object" && !Array.isArray(d)) {
+    const { x, y } = d as Record<string, unknown>;
+    if (typeof x === "number" && typeof y === "number" && Number.isFinite(x) && Number.isFinite(y)) {
+      return { x, y };
+    }
+  }
+  if (Array.isArray(d) && d.length === 2 && d.every((n) => typeof n === "number" && Number.isFinite(n))) {
+    return { x: d[0] as number, y: d[1] as number };
+  }
+  return undefined;
+}
+
+/**
+ * Extract validated moves from a reply. Tolerant of `{"moves":[…]}` or a bare
+ * `[…]`, and of `action`/`id`/`player` aliases. Invalid entries are dropped;
+ * throws DecideError when nothing usable is found (the caller treats that as
+ * "responded without acting").
+ */
+export function parseMoves(text: string): Move[] {
+  const obj = extractJson(text);
+  if (obj == null) throw new DecideError("no JSON found in reply");
+  const arr = Array.isArray(obj)
+    ? obj
+    : Array.isArray((obj as { moves?: unknown }).moves)
+      ? ((obj as { moves: unknown[] }).moves)
+      : null;
+  if (!arr) throw new DecideError("reply JSON has no moves array");
+
+  const valid = new Set<string>(ACTION_TYPES);
+  const moves: Move[] = [];
+  for (const raw of arr) {
+    if (!raw || typeof raw !== "object") continue;
+    const r = raw as Record<string, unknown>;
+    const playerId =
+      typeof r.playerId === "string" ? r.playerId
+        : typeof r.id === "string" ? r.id
+          : typeof r.player === "string" ? r.player
+            : undefined;
+    const type = typeof r.type === "string" ? r.type : typeof r.action === "string" ? r.action : undefined;
+    if (!playerId || !type || !valid.has(type)) continue;
+    const move: Move = { playerId, type };
+    const dir = coerceDir(r.dir);
+    if (dir) move.dir = dir;
+    if (typeof r.power === "number" && Number.isFinite(r.power)) move.power = r.power;
+    if (Number.isInteger(r.zone) && (r.zone as number) >= 1 && (r.zone as number) <= 12) move.zone = r.zone as number;
+    if (typeof r.say === "string") move.say = r.say;
+    moves.push(move);
+  }
+  if (moves.length === 0) throw new DecideError("no valid moves parsed from reply");
+  return moves;
+}
+
+// ── read the agent's reply from the transcript ───────────────────────────────
+
+/** One content block in an assistant message (string content, or an array of
+ *  {type:"text", text} blocks per the OpenClaw transcript shape). */
+function blockText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((b) => {
+        if (typeof b === "string") return b;
+        if (b && typeof b === "object" && typeof (b as { text?: unknown }).text === "string") {
+          return (b as { text: string }).text;
+        }
+        return "";
+      })
+      .join("");
+  }
+  return "";
+}
+
+/** The text of the LAST assistant message in a getSessionMessages transcript.
+ *  A fresh per-turn session yields one user + one assistant record, so this is
+ *  trivially that assistant reply. Returns "" when there is no assistant text. */
+export function lastAssistantText(messages: unknown[]): string {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const m = messages[i];
+    if (m && typeof m === "object" && (m as { role?: unknown }).role === "assistant") {
+      return blockText((m as { content?: unknown }).content);
+    }
+  }
+  return "";
+}
+
+// ── execute: POST one action per move to the pitch ───────────────────────────
+
+export type ExecuteDeps = {
+  /** Pitch base URL (cfg.serverUrl), e.g. http://localhost:3010. */
+  base: string;
+  cfg: PluginCfg;
+  /** Caller DID / agentId (session.did ?? agentId). */
+  did: string;
+  /** Seat token (session.token), sent as x-agent-token. */
+  token?: string | null | undefined;
+  /** Reported as x-agent-decision-ms — the prompt→reply latency (ms). */
+  decisionMs?: number;
+  /** Test seam; defaults to global fetch. */
+  fetch?: typeof fetch;
+};
+
+/**
+ * POST one `/action` per move, carrying the decision-observability headers the
+ * pitch reads (x-agent-model from session.lastModel, x-agent-decision-ms =
+ * prompt→reply latency). Mirrors generate.ts's vfetch act path so capture sees
+ * the same shape. Stamps session.lastActAt on the first successful POST so the
+ * watcher's act-verification sees "we posted moves this cycle".
+ */
+export async function executeMoves(
+  matchId: string,
+  moves: Move[],
+  deps: ExecuteDeps,
+): Promise<{ posted: number; results: { playerId: string; status: number }[] }> {
+  const f = deps.fetch ?? fetch;
+  const base = deps.base.replace(/\/$/, "");
+  const results: { playerId: string; status: number }[] = [];
+  for (const m of moves) {
+    const body: Record<string, unknown> = { agentId: deps.did, type: m.type };
+    if (m.dir) body.dir = m.dir;
+    if (m.power !== undefined) body.power = m.power;
+    if (m.zone !== undefined) body.zone = m.zone;
+    if (m.say !== undefined) body.say = m.say;
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "x-caller-did": deps.did,
+      "x-agent-runtime": "openclaw-plugin/autoplay",
+    };
+    if (deps.token) headers["x-agent-token"] = deps.token;
+    if (session.lastModel) headers["x-agent-model"] = session.lastModel;
+    if (deps.decisionMs !== undefined) headers["x-agent-decision-ms"] = String(Math.max(0, Math.round(deps.decisionMs)));
+    const key = apiKeyOf(deps.cfg);
+    if (key) headers.Authorization = `Bearer ${key}`;
+    const url = `${base}/matches/${encodeURIComponent(matchId)}/players/${encodeURIComponent(m.playerId)}/action`;
+    const res = await f(url, { method: "POST", headers, body: JSON.stringify(body) });
+    if (res.ok) session.lastActAt = Date.now(); // act-verification: the team was moved this cycle
+    results.push({ playerId: m.playerId, status: res.status });
+  }
+  return { posted: results.length, results };
+}
+
+// ── the full autoplay turn: run → wait → read → parse → post ─────────────────
+
+export type AutoplayTurnDeps = {
+  runtime: PluginRuntime;
+  sessionKey: string;
+  idempotencyKey: string;
+  /** The strict-JSON move prompt to deliver to the agent. */
+  message: string;
+  /** Backstop ceiling for waitForRun (the watcher watchdog is the latch backstop). */
+  timeoutMs: number;
+  matchId: string;
+  cfg: PluginCfg;
+  did: string;
+  token?: string | null;
+  base: string;
+  logger?: { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void };
+};
+
+export type AutoplayTurnResult =
+  | { acted: true; via: "post"; posted: number }
+  | { acted: true; via: "tool" }                 // the model called soccer_play itself
+  | { acted: false; reason: string };            // responded without acting (parse miss / empty reply)
+
+/**
+ * Force exactly one agent turn for a delivered situation and act on its reply.
+ * Returns whether the team was acted this cycle (post or tool) or not (the
+ * watcher logs/counts a no-act turn and keeps standing orders — never freezes).
+ */
+export async function runAutoplayTurn(deps: AutoplayTurnDeps): Promise<AutoplayTurnResult> {
+  const { runtime } = deps;
+  // act-verification baseline: if soccer_play runs during this turn it advances
+  // session.lastActAt past this — our cue to NOT double-post.
+  const actAtBefore = session.lastActAt;
+  const startedAt = Date.now();
+
+  const { runId } = await runtime.subagent.run({
+    sessionKey: deps.sessionKey,
+    message: deps.message,
+    deliver: false,
+    idempotencyKey: deps.idempotencyKey,
+  });
+  await runtime.subagent.waitForRun({ runId, timeoutMs: deps.timeoutMs });
+  const decisionMs = Math.max(0, Date.now() - startedAt);
+
+  // The model called the act tool itself (it POSTed + stamped lastActAt). Treat
+  // the cycle as acted; do NOT parse+post again (would double-apply).
+  if (session.lastActAt !== actAtBefore) {
+    return { acted: true, via: "tool" };
+  }
+
+  let text = "";
+  try {
+    const { messages } = await runtime.subagent.getSessionMessages({ sessionKey: deps.sessionKey, limit: 10 });
+    text = lastAssistantText(messages);
+  } catch (e) {
+    deps.logger?.warn(`getSessionMessages failed: ${String(e)}`);
+  } finally {
+    // Fresh session per turn → drop it so transcripts don't accumulate. Cleanup
+    // failure is non-fatal (the run already happened).
+    runtime.subagent.deleteSession({ sessionKey: deps.sessionKey }).catch(() => {});
+  }
+
+  let moves: Move[];
+  try {
+    moves = parseMoves(text);
+  } catch (e) {
+    return { acted: false, reason: e instanceof DecideError ? e.message : String(e) };
+  }
+
+  const { posted } = await executeMoves(deps.matchId, moves, {
+    base: deps.base,
+    cfg: deps.cfg,
+    did: deps.did,
+    token: deps.token,
+    decisionMs,
+  });
+  return { acted: true, via: "post", posted };
+}

package/src/generate.ts

@@ -37,6 +37,10 @@ function did(venueId: string, cfg: PluginCfg): string {
 async function vfetch(base: string, path: string, opts: { method?: string; body?: unknown; cfg: PluginCfg; token?: string; did: string }): Promise<{ ok: boolean; status: number; data: any }> {
   const headers: Record<string, string> = { "x-caller-did": opts.did, "x-agent-runtime": "openclaw-plugin/0.2.0" };
   if (session.lastModel) headers["x-agent-model"] = session.lastModel; // effective LLM for the pitch roster
+  // Prompt→act latency: ms from when the watcher delivered the move prompt to
+  // this call. The pitch reads x-agent-decision-ms to record decision speed. Only
+  // meaningful on the act POST, but harmless elsewhere (server ignores it there).
+  if (session.promptDeliveredAt != null) headers["x-agent-decision-ms"] = String(Math.max(0, Date.now() - session.promptDeliveredAt));
   const key = apiKeyOf(opts.cfg); if (key) headers["Authorization"] = `Bearer ${key}`;
   if (opts.token) headers["x-agent-token"] = opts.token;
   if (opts.body !== undefined) headers["Content-Type"] = "application/json";
@@ -168,6 +172,7 @@ export function generateVenueTools(venue: Venue, spec: GameSpec, cfg: PluginCfg)
             const path = sub(actRoute, { matchId: seat.id ?? "", did: d, playerId: String(m.player ?? "") });
             const body = { agentId: d, type: action, ...whitelist(m, s.params ?? {}), ...(session.lockstep ? { turn: session.turn } : {}) };
             const r = await vfetch(base, path, { cfg, did: d, method: "POST", body, token: seat.token });
+            if (r.ok) session.lastActAt = Date.now(); // act-verification: the agent moved its team this turn
             applied.push(r.ok ? { player: m.player, type: action } : { player: m.player, error: r.data?.error ?? r.status });
           }
           return ok({ applied });
@@ -182,6 +187,7 @@ export function generateVenueTools(venue: Venue, spec: GameSpec, cfg: PluginCfg)
           const path = sub(actRoute, { matchId: seat.id ?? "", did: d, playerId: String(p.player ?? "") });
           const r = await vfetch(base, path, { cfg, did: d, method: "POST", body: { type: action, ...whitelist(p, s.params ?? {}) }, token: seat.token });
           if (!r.ok) return ok({ error: r.data?.error ?? `act ${r.status}` });
+          session.lastActAt = Date.now(); // act-verification: the agent acted this turn
           return ok({ type: action, result: r.data });
         } } as AnyAgentTool);
     }

package/src/state.ts

@@ -23,8 +23,19 @@ export const session: {
    *  the gateway's llm_output hook — sent as x-agent-model so the pitch records
    *  the model that's actually playing (reflects a mid-match /model switch). */
   lastModel: string | null
+  /** Epoch ms when the act tool last SUCCESSFULLY POSTed an action. The watcher
+   *  reads this before/after a delivery to detect "prompted but didn't act"
+   *  (the run finished without the agent moving its team). null until first act. */
+  lastActAt: number | null
+  /** How many delivered prompts completed WITHOUT the agent acting (no advance of
+   *  lastActAt). Pure observability — surfaced for tests/inspection, never gates play. */
+  noActTurns: number
+  /** Epoch ms when the watcher last handed a move prompt to the agent (set right
+   *  before subagent.run). The act tool emits Date.now()-this as the prompt→act
+   *  latency header x-agent-decision-ms. null until the first prompt is delivered. */
+  promptDeliveredAt: number | null
   /** Installed by the service: seat into a venue room (matchId omitted = quickmatch
    *  find-or-create) and start the observe/act loop. `params` are venue join params
    *  (e.g. teamSize/team for soccer). Returns the seat the loop is now driving. */
   joinAndWatch: ((matchId?: string, params?: Record<string, unknown>) => Promise<{ id?: string; controls?: string[]; started?: boolean }>) | null
-} = { matchId: null, players: [], token: null, did: null, turn: 0, lockstep: false, lastModel: null, joinAndWatch: null }
+} = { matchId: null, players: [], token: null, did: null, turn: 0, lockstep: false, lastModel: null, lastActAt: null, noActTurns: 0, promptDeliveredAt: null, joinAndWatch: null }

package/src/tools.ts

@@ -6,6 +6,17 @@ import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import { describeTeam, type TeamView } from "./format.js";
 import { session } from "./state.js";
 
+/** Plugin version from package.json (the file the publish pipeline bumps), read
+ *  once at module load. Sent in x-agent-runtime so the pitch records WHICH
+ *  plugin version holds a seat. Falls back to 'dev' if the manifest is missing. */
+const PLUGIN_VERSION: string = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "dev";
+  } catch {
+    return "dev";
+  }
+})();
+
 export type PluginCfg = {
   serverUrl?: string;
   /** Auto quick-match at startup: find a waiting room (teamSize) or create one.
@@ -178,8 +189,10 @@ export function pitchClient(cfg: PluginCfg) {
     const k = apiKeyOf(cfg);
     return k ? { Authorization: `Bearer ${k}` } : {};
   };
-  // Tells the lobby roster what kind of client holds this seat.
-  const RUNTIME = { "x-agent-runtime": "openclaw-plugin/0.1.0" };
+  // Tells the lobby roster what kind of client — and which VERSION — holds this
+  // seat. PLUGIN_VERSION is read from package.json (bumped by the publish
+  // pipeline) so the pitch can see which plugin build a seat is actually running.
+  const RUNTIME = { "x-agent-runtime": `openclaw-plugin/agent-messier@${PLUGIN_VERSION}` };
   // The room is dynamic. In-process state is set when the watcher joins, but
   // tools may run in a DIFFERENT process (CLI chat, dashboard) — so fall back
   // to asking the server which room this agentId is seated in.

package/src/watcher.ts

@@ -35,8 +35,17 @@ export type WatcherCfg = {
   actTool?: string;
   /** Log tag for this venue's watcher (e.g. "agent-soccer"). Default "agentnet". */
   label?: string;
+  /** Watchdog: max ms a single delivery may hold the in-flight latch. If a
+   *  deliver (subagent run) hangs or runs longer than this, the watcher releases
+   *  the latch, warns, and delivers the freshest frame — so a slow/stuck decision
+   *  can't silence the team for the full subagent timeout. Default 45000. */
+  deliverTimeoutMs?: number;
 };
 
+/** Default per-delivery watchdog (ms). Matches index.ts's waitForRun timeout so
+ *  the latch is released right around when the run would time out anyway. */
+export const DEFAULT_DELIVER_TIMEOUT_MS = 45_000;
+
 // ── human-editable strategy (Phase 5) ────────────────────────────────────────
 // A markdown file the manager edits; injected into the move prompt. mtime-cached
 // (no re-read per tick), refreshed on edit, capped so it can't blow the prompt.
@@ -166,6 +175,8 @@ export async function startObserveWatcher(
       .finally(() => { specFetching = false; });
   }
 
+  const deliverTimeoutMs = cfg.deliverTimeoutMs ?? DEFAULT_DELIVER_TIMEOUT_MS;
+
   function maybeDeliver() {
     if (busy || signal?.aborted || latest === null || latestSeq === deliveredSeq) return;
     // Match over → stop prompting. No message to the gateway = no LLM call.
@@ -173,9 +184,39 @@ export async function startObserveWatcher(
     busy = true;
     const seq = latestSeq;
     const obs = latest;
+    // Act-verification baseline: if the act tool doesn't stamp lastActAt past
+    // this during the run, the agent was prompted but never moved its team.
+    const actAtBefore = session.lastActAt;
+
+    // The watchdog and the deliver race for the latch. Whichever fires FIRST
+    // owns the release; `settled` makes the loser a no-op, so a slow deliver that
+    // resolves AFTER the watchdog can't double-release or re-deliver the same
+    // seq. Without this, a hung deliver (subagent run) would hold `busy` for the
+    // whole subagent timeout and silence the team on stale standing orders.
+    let settled = false;
+    let watchdog: ReturnType<typeof setTimeout> | undefined;
+    const release = (onTimeout: boolean) => {
+      if (settled) return;
+      settled = true;
+      if (watchdog !== undefined) clearTimeout(watchdog);
+      deliveredSeq = seq;
+      busy = false;
+      if (onTimeout) {
+        logger?.warn(`[${tag}] deliver exceeded ${deliverTimeoutMs}ms — releasing latch, agent may be stalled`);
+      } else if (session.lastActAt === actAtBefore) {
+        // The run finished but no action was POSTed — surfaced, never gated.
+        session.noActTurns++;
+        logger?.warn(`[${tag}] agent responded without acting (turn ${seq})`);
+      }
+      maybeDeliver();
+    };
+
+    watchdog = setTimeout(() => release(true), deliverTimeoutMs);
+    signal?.addEventListener("abort", () => { if (watchdog !== undefined) clearTimeout(watchdog); }, { once: true });
+
     Promise.resolve(deliver(prompt(obs, cfg.mode ?? "easy", cfg.strategyFile, spec, actTool)))
       .catch((e) => logger?.error(`[${tag}] deliver failed: ${String(e)}`))
-      .finally(() => { deliveredSeq = seq; busy = false; maybeDeliver(); });
+      .finally(() => release(false));
   }
 
   let attempt = 0;