fix: accept event-driven routing exit

packages/api/src/domains/cats/services/agents/routing/final-routing-slot.ts

@@ -37,6 +37,8 @@ export type ValidationResult =
 const MARKDOWN_LINE_PREFIX_RE = /^(?:(?:>\s*)|(?:[-*+]\s+)|(?:\d+[.)]\s+))+/;
 const URL_RE = /https?:\/\/[^\s)\]]+/g;
 const FENCED_CODE_RE = /```[\s\S]*?```/g;
+const EVENT_DRIVEN_EXTERNAL_WAIT_RE =
+  /^(?:(?:[-*+]\s+)|(?:\d+[.)]\s+))?External Wait\s*:\s*event-driven\s*\((?!\s*\))[^)\r\n]+\)\s*$/i;
 
 /**
  * Extract final routing slot = structurally-stripped last non-empty paragraph.
@@ -72,6 +74,21 @@ export function finalRoutingSlot(text: string): string {
   return paragraphs.length > 0 ? paragraphs[paragraphs.length - 1]! : '';
 }
 
+function slotHasEventDrivenExternalWaitExit(slot: string): boolean {
+  if (!slot) return false;
+  return slot.split(/\r?\n/).some((line) => EVENT_DRIVEN_EXTERNAL_WAIT_RE.test(line.trim()));
+}
+
+/**
+ * True iff the final routing slot contains the documented structural 2b external-wait exit.
+ *
+ * This is deliberately a slot-template check, not a natural-language intent classifier.
+ */
+export function hasEventDrivenExternalWaitExit(text: string | undefined): boolean {
+  if (!text) return false;
+  return slotHasEventDrivenExternalWaitExit(finalRoutingSlot(text));
+}
+
 /**
  * Find inline @handle mentions in slot (= not at line-start position).
  *
@@ -132,6 +149,7 @@ export function findInlineMentionsInSlot(slot: string, rosterHandles: readonly s
  *   - legitimate line-start @mention present
  *   - hold_ball tool call present
  *   - structured MCP routing (targetCats / multi_mention targets) present
+ *   - structural 2b external wait slot present
  *   - no inline @handle inside final routing slot
  *
  * Returns `invalid_route_syntax` when NONE of the above AND slot has inline @handle.
@@ -142,6 +160,8 @@ export function validateRoutingSyntax(input: ValidationInput): ValidationResult
   if (input.structuredTargetCats.length > 0) return { kind: 'ok' };
 
   const slot = finalRoutingSlot(input.text);
+  if (slotHasEventDrivenExternalWaitExit(slot)) return { kind: 'ok' };
+
   const inlineMentions = findInlineMentionsInSlot(slot, input.rosterHandles);
   if (inlineMentions.length === 0) return { kind: 'ok' };
 

packages/api/src/domains/cats/services/agents/routing/guards/routing-guard-remedial.ts

@@ -12,6 +12,8 @@
  * KD-8 safe：只看"有无机械出口信号"，零意图分类器。
  */
 
+import { hasEventDrivenExternalWaitExit } from '../final-routing-slot.js';
+
 /** Routing-tool substrings that count as a legitimate exit (持球/群发传球). */
 const ROUTING_TOOL_SUBSTRINGS = ['hold_ball', 'multi_mention'] as const;
 
@@ -23,6 +25,8 @@ function hasRoutingToolCall(toolNames: readonly string[]): boolean {
 }
 
 export interface RoutingExitInput {
+  /** Stored output text. Only the final routing slot is inspected for structural external-wait exits. */
+  readonly text?: string;
   /** Line-start @cat mentions parsed this turn (parseA2AMentions). */
   readonly lineStartMentions: readonly string[];
   /** Tool names invoked this turn (scan for hold_ball / multi_mention). */
@@ -36,13 +40,15 @@ export interface RoutingExitInput {
 /**
  * True iff the turn has a legitimate routing exit (传球 / 持球 / 升级).
  * Mirrors the suppression set of evaluateVoidHold + F177-G hook
- * (line-start @, hold_ball, multi_mention, targetCats, co-creator).
+ * (line-start @, hold_ball, multi_mention, targetCats, co-creator, structural
+ * 2b external wait slot).
  */
 export function hasValidRoutingExit(input: RoutingExitInput): boolean {
   if (input.lineStartMentions.length > 0) return true;
   if (input.structuredTargetCats.length > 0) return true;
   if (input.hasCoCreatorLineStartMention) return true;
   if (hasRoutingToolCall(input.toolNames)) return true;
+  if (hasEventDrivenExternalWaitExit(input.text)) return true;
   return false;
 }
 
@@ -74,6 +80,7 @@ export const REMEDIAL_PROMPT =
   '请只补一个出口，不要重做刚才的工作：\n' +
   '- 传球：另起一行，行首独立写 @句柄（如 @opus48）\n' +
   '- 持球等外部条件：调用 cat_cafe_hold_ball\n' +
+  '- 事件驱动外部等待（已有结构化回调 + EYES>0）：另起一行写 External Wait: event-driven (<id>)\n' +
   '- 升级co-creator：另起一行行首写 @co-creator';
 
 export function buildRemedialPrompt(): string {

packages/api/src/domains/cats/services/agents/routing/route-serial.ts

@@ -1732,6 +1732,7 @@ export async function* routeSerial(
         shouldRemediateRouting({
           needsGuard: needsServerRoutingGuard,
           attempted: routingGuardAttempted,
+          text: '',
           lineStartMentions: getRoutingExitLineStartMentions(),
           toolNames: collectedToolNames,
           structuredTargetCats: [...structuredTargetCats],
@@ -1748,6 +1749,7 @@ export async function* routeSerial(
         noTextBlocksOverride = result.allRichBlocks;
         if (
           !hasValidRoutingExit({
+            text: result.storedContent,
             lineStartMentions: getRoutingExitLineStartMentions(result.a2aMentions),
             toolNames: collectedToolNames,
             structuredTargetCats: [...structuredTargetCats],
@@ -1799,6 +1801,7 @@ export async function* routeSerial(
           shouldRemediateRouting({
             needsGuard: needsServerRoutingGuard,
             attempted: routingGuardAttempted,
+            text: storedContent,
             lineStartMentions: routingExitLineStartMentions,
             toolNames: collectedToolNames,
             structuredTargetCats: [...structuredTargetCats],
@@ -1816,6 +1819,7 @@ export async function* routeSerial(
 
           if (
             !hasValidRoutingExit({
+              text: storedContent,
               lineStartMentions: routingExitLineStartMentions,
               toolNames: collectedToolNames,
               structuredTargetCats: [...structuredTargetCats],

packages/api/test/final-routing-slot.test.js

@@ -151,6 +151,17 @@ describe('F167 Phase H AC-H3: validateRoutingSyntax trigger conditions', () => {
     });
     assert.equal(result.kind, 'ok');
   });
+
+  test('2b event-driven external wait exit suppresses inline mention syntax warning', () => {
+    const result = validateRoutingSyntax({
+      text: '不再 @codex。\nExternal Wait: event-driven (pr:35)',
+      lineStartMentions: [],
+      toolNames: [],
+      structuredTargetCats: [],
+      rosterHandles: roster,
+    });
+    assert.equal(result.kind, 'ok');
+  });
 });
 
 describe('F167 Phase H AC-H6: structural exemptions', () => {

packages/api/test/route-serial-routing-guard-remedial.test.js

@@ -664,6 +664,25 @@ describe('F177 Phase H — route-serial routing guard remedial invoke', () => {
     assert.deepEqual(spokenChunks, ['我先持球继续。'], 'voice TTS should match the preserved live text');
   });
 
+  test('2b event-driven external wait final slot counts as a routing exit without remedial invoke', async () => {
+    const service = createSequenceService('codex', [
+      'cloud / CI 已有结构化回调覆盖，不需要 hold_ball。\n\nExternal Wait: event-driven (pr:clowder-labs/clowder-ai#32)',
+      '@co-creator',
+    ]);
+
+    const { appended, calls } = await runRoute(service, 'thread-routing-guard-event-driven-wait');
+
+    assert.equal(calls.length, 1, 'explicit 2b event-driven external wait should not trigger remedial invoke');
+    assert.equal(
+      appended.find((m) => m.source?.connector === 'routing-guard-failure'),
+      undefined,
+      'event-driven external wait should not emit routing guard failure',
+    );
+    const codexMessages = appended.filter((m) => m.catId === 'codex' && m.origin === 'stream');
+    assert.equal(codexMessages.length, 1);
+    assert.match(codexMessages[0].content, /External Wait: event-driven/);
+  });
+
   test('guard-disabled cat still runs once and keeps legacy non-blocking hint behavior', async () => {
     const service = createSequenceService('codex', ['I will keep going from here.'], { needsGuard: false });
 

packages/api/test/routing-guard-remedial.test.js

@@ -75,6 +75,18 @@ describe('F177 Phase H — shouldRemediateRouting', () => {
       true,
     );
   });
+
+  test('2b External Wait event-driven 槽位 → 不触发 remedial', () => {
+    assert.equal(
+      shouldRemediateRouting({
+        ...base,
+        text: 'cloud / CI 已有结构化回调覆盖。\n\nExternal Wait: event-driven (pr:clowder-ai#32)',
+        needsGuard: true,
+        attempted: false,
+      }),
+      false,
+    );
+  });
 });
 
 describe('F177 Phase H — hasValidRoutingExit', () => {
@@ -88,13 +100,24 @@ describe('F177 Phase H — hasValidRoutingExit', () => {
     assert.equal(hasValidRoutingExit({ ...base, structuredTargetCats: ['x'] }), true);
     assert.equal(hasValidRoutingExit({ ...base, hasCoCreatorLineStartMention: true }), true);
   });
+
+  test('External Wait: event-driven(<id>) counts as a valid 2b external-wait exit', () => {
+    assert.equal(
+      hasValidRoutingExit({
+        ...base,
+        text: '结论：已有结构化回调 + EYES>0，不续 hold_ball。\n\nExternal Wait: event-driven (github-pr-32)',
+      }),
+      true,
+    );
+  });
 });
 
 describe('F177 Phase H — buildRemedialPrompt', () => {
-  test('含路由指引（行首 @ / hold_ball / @co-creator）且明确不重做工作', () => {
+  test('含路由指引（行首 @ / hold_ball / event-driven / @co-creator）且明确不重做工作', () => {
     const p = buildRemedialPrompt();
     assert.match(p, /行首/);
     assert.match(p, /hold_ball/);
+    assert.match(p, /event-driven/);
     assert.match(p, /@co-creator/);
     assert.match(p, /不要重做/);
   });

review-notes/2026-06-28-route-guard-2b-event-driven-review-request.md

@@ -0,0 +1,146 @@
+# Review Request: route guard 2b event-driven external wait
+
+Review-Target-ID: fix-route-guard-2b-event-driven
+Branch: fix/route-guard-2b-event-driven
+Target: local branch based on `origin/main` at `8e412d2b`
+
+## What
+
+The routing guard now treats a final-slot line of
+`External Wait: event-driven (<id>)` as a legitimate 2b external-wait exit.
+
+Changed paths:
+- `packages/api/src/domains/cats/services/agents/routing/guards/routing-guard-remedial.ts`
+- `packages/api/src/domains/cats/services/agents/routing/route-serial.ts`
+- `packages/api/test/routing-guard-remedial.test.js`
+- `packages/api/test/route-serial-routing-guard-remedial.test.js`
+
+## Why
+
+Daily patrol found a real routing contradiction: when PR tracking had structured
+callback coverage and EYES>0, the collaboration rule said 2b event-driven wait
+means no `hold_ball`, but the server-side routing guard rejected the response as
+"no legal route exit" unless it saw line-start `@` or `cat_cafe_hold_ball`.
+That caused unnecessary remedial churn and local cat ping-pong even though the
+next action was an external callback.
+
+## Original Requirements
+
+Source: scheduled patrol in `thread_mqcj45byxoka2z7u`, wake
+`2026-06-28 00:00 Asia/Shanghai`.
+
+> 每轮必须先查真相源和证据，再给风险/价值判断与下一步动作。
+> 发现可执行事项后主导闭环：按家规走 feature lifecycle（定位真相源、立项、实现/协调、质量门禁、review、完成记录）。
+
+Observed incident source: `clowder-labs/clowder-ai#32` review/check wait path
+where current rules selected 2b event-driven waiting but route guard demanded
+`@` or `hold_ball`.
+
+## Tradeoff
+
+This is intentionally structural: only a final routing slot line matching
+`External Wait: event-driven (<id>)` counts. It does not classify natural
+language like "I will wait for CI", so the F177/KD-8 guard remains mechanical.
+
+The remedial prompt now teaches that exact outlet format, so future guard
+patches can add the missing exit without redoing work.
+
+## Architecture Ownership
+
+Architecture cell: routing / A2A guard
+Map delta: none
+Why: this extends the existing routing guard exit predicate and route-serial
+input plumbing. It does not add a new Store, Queue, Router, Adapter, Dispatcher,
+Binding, runtime service, or external contract.
+
+Please check:
+- diff matches `Map delta: none`
+- the `External Wait` recognizer is structural enough and not an intent classifier
+- route-serial passes the correct stored text at every guard check
+
+## Quality Gate Evidence
+
+### Red
+
+- `routing-guard-remedial.test.js`: `2b External Wait event-driven 槽位 → 不触发 remedial` failed, returning `true` instead of `false`.
+- `routing-guard-remedial.test.js`: `External Wait: event-driven(<id>) counts as a valid 2b external-wait exit` failed, returning `false` instead of `true`.
+- `routing-guard-remedial.test.js`: prompt test failed because `event-driven` was missing.
+- `route-serial-routing-guard-remedial.test.js`: event-driven external wait caused two Codex invocations instead of one.
+
+### Green
+
+- `pnpm --dir packages/api run build`: passed
+- `CAT_CAFE_DISABLE_SHARED_STATE_PREFLIGHT=1 bash packages/api/scripts/with-test-home.sh node --import $(pwd)/packages/api/test/helpers/setup-cat-registry.js --test --test-timeout=60000 packages/api/test/routing-guard-remedial.test.js packages/api/test/route-serial-routing-guard-remedial.test.js`: 33 tests passed
+- `CAT_CAFE_DISABLE_SHARED_STATE_PREFLIGHT=1 bash packages/api/scripts/with-test-home.sh node --import $(pwd)/packages/api/test/helpers/setup-cat-registry.js --test --test-timeout=60000 packages/api/test/final-routing-slot.test.js packages/api/test/verdict-detect.test.js`: 57 tests passed
+- `pnpm --dir packages/api run lint`: passed
+- `git diff --check`: passed
+- `pnpm check`: passed
+
+### Extra Gate Checks
+
+- `node scripts/check-hotfix-pattern.mjs`: `{"hotfix":false,"matchedTerms":[],"matches":[]}`
+- `node scripts/check-fallback-layers.mjs`: N/A, script is not present in this tree.
+- `pnpm run check:architecture-ownership`: N/A, script is not present in this tree.
+- `rg --files designs | rg '\.pen$'`: N/A, `designs/` is not present.
+- Root artifact hygiene:
+  - `git status --short | rg '^.. [^/]+\.(png|jpe?g|webp|gif|webm|mp4|mov|wav|pdf|pen)$'`: no output
+  - `git diff --name-only origin/main...HEAD | rg '^[^/]+\.(png|jpe?g|webp|gif|webm|mp4|mov|wav|pdf|pen)$'`: no output
+
+### Dogfood-Your-Slice
+
+Scope verdict: required. This is cat-visible routing behavior.
+
+Dogfood path: the route-serial integration suite exercises a guarded Codex turn
+whose final slot is `External Wait: event-driven (pr:clowder-labs/clowder-ai#32)`.
+Before the fix, route-serial invoked Codex twice; after the fix, it persists the
+original visible response with one invocation and no routing-guard failure.
+
+## Open Questions
+
+### Technical OQ
+
+- Should we accept only the English `External Wait` template, or also add a
+  separate Chinese canonical template later? This patch keeps the existing
+  documented template only.
+- Is line-level matching inside the final slot acceptable, or should the entire
+  final paragraph be exactly one `External Wait` line?
+
+### Value OQ
+
+None.
+
+## Next Action
+
+Please do a non-author review of `fix/route-guard-2b-event-driven`. If clean,
+approve and include the focused validation you ran. If there are P1/P2 findings,
+route back to `@codex` for receive-review.
+
+## Receive-Review Update
+
+Reviewer found one P2 on current head `a9e177d8`: `External Wait: event-driven`
+was accepted by `routing-guard-remedial`, but Phase H `validateRoutingSyntax`
+still treated an inline mention in the same final slot as `invalid_route_syntax`.
+
+Fix:
+- moved the structural event-driven external-wait predicate into
+  `final-routing-slot.ts`
+- made `routing-guard-remedial.ts` reuse that shared helper
+- taught `validateRoutingSyntax()` to treat the same final-slot event-driven
+  exit as a legitimate syntax suppressor
+
+Red→Green:
+- `2b event-driven external wait exit suppresses inline mention syntax warning`
+  failed with `invalid_route_syntax`, now passes with `ok`.
+
+Failure-mode sweep:
+- Pattern: newly added legitimate route exit must be recognized consistently by
+  every mechanical routing guard in this PR.
+- Scanned touched routing guard surfaces: remedial exit predicate, route-serial
+  guard invocation sites, Phase H final-slot syntax validator, verdict adjacent
+  tests.
+- Result: shared helper now prevents remedial/Phase-H drift for this exit.
+
+Additional verification after the fix:
+- `pnpm --dir packages/api run build`: passed
+- `CAT_CAFE_DISABLE_SHARED_STATE_PREFLIGHT=1 bash packages/api/scripts/with-test-home.sh node --import $(pwd)/packages/api/test/helpers/setup-cat-registry.js --test --test-timeout=60000 packages/api/test/final-routing-slot.test.js`: 23 tests passed
+- `CAT_CAFE_DISABLE_SHARED_STATE_PREFLIGHT=1 bash packages/api/scripts/with-test-home.sh node --import $(pwd)/packages/api/test/helpers/setup-cat-registry.js --test --test-timeout=60000 packages/api/test/routing-guard-remedial.test.js packages/api/test/route-serial-routing-guard-remedial.test.js packages/api/test/verdict-detect.test.js`: 68 tests passed