@yeaft/webchat-agent 0.1.510 → 0.1.511

package/connection/message-router.js

@@ -1,3 +1,14 @@
+/**
+ * message-router.js — Server-bound message dispatcher.
+ *
+ * task-330c lint guard:
+ *   ⚠️ DO NOT introduce greedy `text.replace(/---ROUTE---[\s\S]*$/g, '')`
+ *      style strips on routed message payloads. Crew ROUTE stripping is
+ *      owned EXCLUSIVELY by `agent/crew/routing.js` `parseRoutes()` which
+ *      returns `{routes, displayBody}` with exact ranges removed. A second
+ *      strip here would re-process already-cleaned text and risks both
+ *      double-strip artefacts and the trailing-prose bug fixed by task-328.
+ */
 import ctx from '../context.js';
 import { decodeKey } from '../encryption.js';
 import { handleTerminalCreate, handleTerminalInput, handleTerminalResize, handleTerminalClose } from '../terminal.js';

package/crew/builtin-actions.js

@@ -0,0 +1,154 @@
+/**
+ * Crew — built-in role actions (task-330a §B)
+ *
+ * These two actions replace the "PM 给自己发闭环消息" anti-pattern that
+ * task-330a §A now rejects at the routing layer:
+ *
+ *   • taskClose(session, { taskId, summary, fromRole })
+ *       — directly mark the task complete on the kanban + broadcast a
+ *         status card via sendCrewMessage. No ROUTE round-trip.
+ *
+ *   • roleStandby(session, { role, reason, fromRole })
+ *       — flip a role's runtime state to 'standby' and broadcast.
+ *         Persistence to .crew/context/role-states.json is a 330d
+ *         concern — we only define the in-memory contract here.
+ *
+ * Both functions are pure server-side helpers. They do NOT consume a
+ * routing turn (no session.round++, no dispatchToRole). Callers that
+ * choose to expose them as Claude tools (via canCallTool / mcp) must
+ * wire that separately — task-330a defines the contract; tool-binding
+ * lands in 330d alongside the role-state persistence layer.
+ *
+ * Red lines (per PM dispatch):
+ *   - Do not mutate routing protocol shape (.routes / displayBody).
+ *   - Do not break task-319/328 (parser tests stay green).
+ *   - Old session replay must keep working — we only add new keys to
+ *     session.roleStates[role], never remove.
+ */
+
+import { sendCrewMessage, sendStatusUpdate } from './ui-messages.js';
+import { updateKanban, appendChangelog, updateFeatureIndex, isValidTaskId } from './task-files.js';
+
+/** Valid standby reasons — extend with care; consumers may grep for these. */
+export const STANDBY_REASONS = Object.freeze([
+  'task_closed', 'awaiting_input', 'manual', 'idle', 'paused',
+]);
+
+/**
+ * Mark a task as complete on the kanban + broadcast a status card.
+ *
+ * Mirrors the side-effects that role-output.js performs when it detects a
+ * completed TASKS block, so the two paths converge on the same kanban
+ * state regardless of which one fires.
+ *
+ * @param {object} session
+ * @param {{ taskId: string, summary?: string, fromRole?: string }} params
+ * @returns {Promise<{ ok: boolean, taskId: string, reason?: string }>}
+ */
+export async function taskClose(session, { taskId, summary, fromRole }) {
+  if (!session) {
+    return { ok: false, taskId: taskId || null, reason: 'no_session' };
+  }
+  if (!taskId || !isValidTaskId(taskId)) {
+    return { ok: false, taskId: taskId || null, reason: 'invalid_task_id' };
+  }
+
+  // Mark in the in-memory completion set so future kanban rebuilds keep it.
+  if (!session._completedTaskIds) session._completedTaskIds = new Set();
+  const wasAlreadyCompleted = session._completedTaskIds.has(taskId);
+  session._completedTaskIds.add(taskId);
+
+  const feature = session.features?.get(taskId);
+  const taskTitle = feature?.taskTitle || taskId;
+  const cleanSummary = (summary && String(summary).trim()) || '已完成';
+
+  // Persist to the kanban file (best-effort; warns on failure).
+  try {
+    await updateKanban(session, { taskId, completed: true, summary: cleanSummary });
+  } catch (e) {
+    console.warn(`[Crew] taskClose: updateKanban failed for ${taskId}:`, e.message);
+  }
+
+  // Append to features index + changelog only on first close (idempotent).
+  if (!wasAlreadyCompleted) {
+    updateFeatureIndex(session)
+      .catch(e => console.warn('[Crew] taskClose: updateFeatureIndex failed:', e.message));
+    appendChangelog(session, taskId, taskTitle)
+      .catch(e => console.warn(`[Crew] taskClose: appendChangelog failed for ${taskId}:`, e.message));
+  }
+
+  // Broadcast status card so the UI reflects the close immediately.
+  try {
+    sendCrewMessage({
+      type: 'crew_task_closed',
+      sessionId: session.id,
+      taskId,
+      taskTitle,
+      summary: cleanSummary,
+      fromRole: fromRole || null,
+      timestamp: Date.now(),
+    });
+    sendStatusUpdate(session);
+  } catch (e) {
+    console.warn(`[Crew] taskClose: broadcast failed for ${taskId}:`, e.message);
+  }
+
+  return { ok: true, taskId };
+}
+
+/**
+ * Flip a role into 'standby' (in-memory) and broadcast.
+ *
+ * 330a defines the contract; 330d wires the .crew/context/role-states.json
+ * persistence. We DO mutate `session.roleStates[role].standby` here so the
+ * UI / status pipeline can reflect the change immediately, and 330d can
+ * snapshot it on the next debounced save.
+ *
+ * @param {object} session
+ * @param {{ role: string, reason?: string, fromRole?: string }} params
+ * @returns {{ ok: boolean, role: string, reason?: string }}
+ */
+export function roleStandby(session, { role, reason, fromRole }) {
+  if (!session) {
+    return { ok: false, role: role || null, reason: 'no_session' };
+  }
+  if (!role || typeof role !== 'string') {
+    return { ok: false, role: role || null, reason: 'invalid_role' };
+  }
+  if (!session.roles || !session.roles.has(role)) {
+    return { ok: false, role, reason: 'unknown_role' };
+  }
+
+  const normalizedReason = reason && STANDBY_REASONS.includes(reason)
+    ? reason
+    : 'manual';
+
+  // Ensure the roleState bucket exists (cold-start safe).
+  let roleState = session.roleStates?.get?.(role);
+  if (!roleState) {
+    roleState = {};
+    session.roleStates?.set?.(role, roleState);
+  }
+  // New keys only — never delete legacy fields (replay safety).
+  roleState.standby = {
+    reason: normalizedReason,
+    since: Date.now(),
+    setBy: fromRole || null,
+  };
+
+  try {
+    sendCrewMessage({
+      type: 'crew_role_standby',
+      sessionId: session.id,
+      role,
+      reason: normalizedReason,
+      fromRole: fromRole || null,
+      timestamp: Date.now(),
+    });
+    sendStatusUpdate(session);
+  } catch (e) {
+    console.warn(`[Crew] roleStandby: broadcast failed for ${role}:`, e.message);
+  }
+
+  return { ok: true, role, reason: normalizedReason };
+}

package/crew/role-output.js

@@ -7,6 +7,8 @@ import { saveRoleSessionId, clearRoleSessionId, classifyRoleError, createRoleQue
 import { parseRoutes, executeRoute, dispatchToRole } from './routing.js';
 import { parseCompletedTasks, updateFeatureIndex, appendChangelog, saveRoleWorkSummary, updateKanban } from './task-files.js';
 import { debouncedSaveSessionMeta, saveSessionMeta } from './persistence.js';
+import { recordRoutingEvent } from './routing-metrics.js';
+import { resolveFallbackTarget } from './routing-fallback.js';
 import ctx from '../context.js';
 
 // Context 使用率常量（运行时从 ctx.CONFIG 读取）
@@ -160,10 +162,29 @@ export async function processRoleOutput(session, roleName, roleQuery, roleState)
         const parseResult = parseRoutes(roleState.accumulatedText);
         const routes = parseResult;
         const displayBody = parseResult.displayBody || roleState.accumulatedText;
-        // Fallback: 如果 route summary 仍为空占位符，用 accumulatedText 末尾 500 字符
+        // task-330b §B item 1: detect "parse-fail" — text mentions a ROUTE
+        // opener but nothing parseable came out. Counts as a separate metric
+        // from plain missing-route so dashboards can split malformed-block
+        // (likely template/prompt drift) from forgot-to-write-block.
+        if (routes.length === 0 && /---\s*ROUTE\s*---/i.test(roleState.accumulatedText || '')) {
+          recordRoutingEvent(session, 'parse-fail', {
+            fromRole: roleName,
+            taskId: roleState.currentTask?.taskId || null,
+            note: 'ROUTE opener present but no parseable block',
+          });
+        }
+        // Fallback: 如果 route summary 仍为空占位符，用 displayBody 末尾 500 字符
+        // task-330c: source switched from `accumulatedText.slice(-500)` to
+        // `displayBody.slice(-500)` — accumulatedText still contains
+        // ---ROUTE--- markers; using it would re-strip already-stripped text
+        // and risk truncating mid-marker. displayBody is the parser's
+        // post-strip prose and is the single source of truth for "what the
+        // role said outside its routing blocks".
+        // ⚠️ DO NOT add any further `.replace(/---ROUTE---.../g, '')` on
+        //    `displayBody` here or downstream — it is already strip-clean.
         for (const route of routes) {
-          if (route.summary === '[该角色未提供消息摘要]' && roleState.accumulatedText) {
-            const tail = roleState.accumulatedText.slice(-500).trim();
+          if (route.summary === '[该角色未提供消息摘要]' && displayBody) {
+            const tail = displayBody.slice(-500).trim();
             if (tail) route.summary = `[auto-extracted]\n${tail}`;
           }
         }
@@ -265,27 +286,59 @@ export async function processRoleOutput(session, roleName, roleQuery, roleState)
           });
           sendStatusUpdate(session);
         } else {
-          // ★ No ROUTE found — decide whether to auto-forward to PM
-          const isNonPM = roleName !== session.decisionMaker;
+          // ★ No ROUTE found — resolve via the single fallback policy
+          // (task-330b §B item 3). The resolver enforces:
+          //   - PM never auto-forwards to itself (parks pending instead)
+          //   - non-PM with active task / routing intent → PM (auto-forward)
+          //   - everyone else → null (process human queue)
           const hasActiveTask = !!roleState.currentTask;
           const hasRouteIntent = _detectRouteIntent(roleState.lastTurnText);
+          const fallbackTo = resolveFallbackTarget(session, roleName, 'missing-route', {
+            hasActiveTask,
+            hasRouteIntent,
+          });
 
-          if (isNonPM && (hasActiveTask || hasRouteIntent)) {
-            // Non-PM role with active task OR routing intent but no ROUTE block:
-            // auto-forward to PM so the message doesn't get lost.
+          if (fallbackTo) {
+            // §B item 1 — record the metric on every fallback dispatch.
+            const reason = hasActiveTask ? 'has active task' : 'has routing intent';
+            recordRoutingEvent(session, 'fallback-forward', {
+              fromRole: roleName,
+              toRole: fallbackTo,
+              taskId: roleState.currentTask?.taskId || null,
+              note: reason,
+            });
+            // Also record the upstream cause so dashboards can split
+            // "missing ROUTE" events from the auto-forward dispatches.
+            recordRoutingEvent(session, 'missing-route', {
+              fromRole: roleName,
+              taskId: roleState.currentTask?.taskId || null,
+              note: reason,
+            });
             // task-328: forward parser-clean displayBody (ROUTE residue removed)
             // so PM sees the actual prose, not stray END markers.
-            const reason = hasActiveTask ? 'has active task' : 'has routing intent';
-            console.log(`[Crew] ${roleName} turn ended without ROUTE (${reason}) — auto-forwarding to PM`);
+            console.log(`[Crew] ${roleName} turn ended without ROUTE (${reason}) — auto-forwarding to ${fallbackTo}`);
             const forwardSource = roleState.lastTurnDisplayBody || roleState.lastTurnText || '';
             const autoSummary = `[auto-forward: ${roleName} turn 结束但未输出 ROUTE 块 (${reason})]\n${forwardSource.slice(-800).trim()}`;
             await executeRoute(session, roleName, {
-              to: session.decisionMaker,
+              to: fallbackTo,
               summary: autoSummary,
               taskId: roleState.currentTask?.taskId || null,
               taskTitle: roleState.currentTask?.taskTitle || null,
             });
           } else {
+            // §B item 2 — PM no-auto-forward: when PM ends a turn without
+            // ROUTE we DO NOT self-route. Instead we record the metric and
+            // park the session (effectively pending) so the user's next
+            // input drives the next step. Same applies to non-PM roles
+            // with no active task / no routing intent.
+            if (roleName === session.decisionMaker && (hasActiveTask || hasRouteIntent)) {
+              recordRoutingEvent(session, 'missing-route', {
+                fromRole: roleName,
+                taskId: roleState.currentTask?.taskId || null,
+                note: 'pm-pending (no auto-forward)',
+              });
+              console.log(`[Crew] ${roleName} (PM) turn ended without ROUTE — staying pending (no self-forward)`);
+            }
             const { processHumanQueue } = await import('./human-interaction.js');
             await processHumanQueue(session);
           }

package/crew/role-states.js

@@ -0,0 +1,180 @@
+/**
+ * Crew — Role State Store (task-330d, Fowler Final Spec §D)
+ *
+ * Replaces the legacy "standby task" pattern (where PM idle was modelled
+ * as a synthetic task in `.crew/context/features/standby.md`). Role idle/
+ * busy/pending state is now first-class and persisted to a single file:
+ *
+ *     <sharedDir>/context/role-states.json
+ *
+ * File shape:
+ *   {
+ *     "version": 1,
+ *     "states": {
+ *       "<roleName>": { role, status, since, reason }
+ *     }
+ *   }
+ *
+ * Status values:
+ *   - 'standby' : role has no active task and is waiting for routing
+ *   - 'busy'    : role is currently executing a turn
+ *   - 'pending' : role finished a turn but did not emit a ROUTE
+ *
+ * Public API (consumed by the `role_standby` tool added in task-330a):
+ *   - getRoleState(sharedDir, role)        → state | null
+ *   - setRoleState(sharedDir, role, patch) → state
+ *   - listRoleStates(sharedDir)            → Record<role, state>
+ *
+ * Atomicity: writes go to `role-states.json.tmp` then rename, matching the
+ * convention in persistence.js. A per-process write lock (Promise chain)
+ * serialises concurrent setRoleState calls so the file never tears.
+ *
+ * Backward compatibility: a session that was created before role-states.json
+ * existed simply has no file; getRoleState returns null and setRoleState
+ * creates the file lazily. No migration step is required.
+ */
+
+import { promises as fs } from 'fs';
+import { join } from 'path';
+
+const FILE_NAME = 'role-states.json';
+const VERSION = 1;
+const VALID_STATUSES = new Set(['standby', 'busy', 'pending']);
+
+// Per-sharedDir write lock. Keyed by absolute path so multiple sessions in
+// one process don't serialise against each other.
+const _writeLocks = new Map();
+
+function _lockKey(sharedDir) {
+  return sharedDir;
+}
+
+function _filePath(sharedDir) {
+  return join(sharedDir, 'context', FILE_NAME);
+}
+
+async function _readAll(sharedDir) {
+  try {
+    const raw = await fs.readFile(_filePath(sharedDir), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.states || typeof parsed.states !== 'object') {
+      return { version: VERSION, states: {} };
+    }
+    return { version: parsed.version || VERSION, states: parsed.states };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { version: VERSION, states: {} };
+    // Corrupt JSON → start fresh rather than crash. This matches the
+    // "legacy session replay compatibility" red line: a broken file must
+    // not block resume.
+    return { version: VERSION, states: {} };
+  }
+}
+
+async function _writeAtomic(sharedDir, payload) {
+  const dir = join(sharedDir, 'context');
+  await fs.mkdir(dir, { recursive: true });
+  const target = _filePath(sharedDir);
+  const tmp = target + '.tmp';
+  await fs.writeFile(tmp, JSON.stringify(payload, null, 2));
+  await fs.rename(tmp, target);
+}
+
+/**
+ * Read the current state for a single role.
+ * @param {string} sharedDir — session shared directory (`.crew` root)
+ * @param {string} role — role name
+ * @returns {Promise<null | {role:string, status:string, since:number, reason?:string}>}
+ */
+export async function getRoleState(sharedDir, role) {
+  if (!sharedDir || !role) return null;
+  const all = await _readAll(sharedDir);
+  return all.states[role] || null;
+}
+
+/**
+ * Read every role's state at once. Returns a plain object keyed by role
+ * name (empty when the file is missing).
+ */
+export async function listRoleStates(sharedDir) {
+  if (!sharedDir) return {};
+  const all = await _readAll(sharedDir);
+  return { ...all.states };
+}
+
+/**
+ * Patch a single role's state. Unspecified fields are preserved from the
+ * existing record. `since` defaults to Date.now() when status changes (or
+ * when no prior record exists). Throws on invalid status — callers are
+ * expected to pass one of standby|busy|pending.
+ *
+ * @param {string} sharedDir
+ * @param {string} role
+ * @param {Partial<{status:string, reason:string, since:number}>} patch
+ * @returns {Promise<{role:string, status:string, since:number, reason?:string}>}
+ */
+export async function setRoleState(sharedDir, role, patch = {}) {
+  if (!sharedDir) throw new Error('setRoleState: sharedDir required');
+  if (!role) throw new Error('setRoleState: role required');
+  if (patch.status !== undefined && !VALID_STATUSES.has(patch.status)) {
+    throw new Error(`setRoleState: invalid status '${patch.status}'`);
+  }
+
+  const key = _lockKey(sharedDir);
+  const prev = _writeLocks.get(key) || Promise.resolve();
+
+  const next = prev.then(async () => {
+    const all = await _readAll(sharedDir);
+    const existing = all.states[role] || null;
+    const statusChanged = patch.status !== undefined && (!existing || existing.status !== patch.status);
+    const merged = {
+      role,
+      status: patch.status !== undefined ? patch.status : (existing ? existing.status : 'standby'),
+      since: patch.since !== undefined
+        ? patch.since
+        : (statusChanged || !existing ? Date.now() : existing.since),
+    };
+    if (patch.reason !== undefined) {
+      merged.reason = patch.reason;
+    } else if (existing && existing.reason !== undefined && !statusChanged) {
+      merged.reason = existing.reason;
+    }
+    all.states[role] = merged;
+    all.version = VERSION;
+    await _writeAtomic(sharedDir, all);
+    return merged;
+  }, async () => {
+    // If a prior write rejected we still want to attempt this one rather
+    // than poisoning the chain forever.
+    const all = await _readAll(sharedDir);
+    const merged = {
+      role,
+      status: patch.status || 'standby',
+      since: patch.since !== undefined ? patch.since : Date.now(),
+      ...(patch.reason !== undefined ? { reason: patch.reason } : {}),
+    };
+    all.states[role] = merged;
+    await _writeAtomic(sharedDir, all);
+    return merged;
+  });
+
+  // Hold onto the chain so the next caller waits on this write.
+  _writeLocks.set(key, next.catch(() => {}));
+  return next;
+}
+
+/**
+ * Test/diagnostic helper — clear in-process write lock for a sharedDir.
+ * Production callers should never need this; tests use it between runs to
+ * avoid bleeding lock state across describe blocks.
+ */
+export function __resetWriteLockForTests(sharedDir) {
+  if (sharedDir) _writeLocks.delete(sharedDir);
+  else _writeLocks.clear();
+}
+
+/**
+ * Constants exported for tests + downstream consumers (the `role_standby`
+ * tool in task-330a).
+ */
+export const ROLE_STATE_FILE_NAME = FILE_NAME;
+export const ROLE_STATE_STATUSES = ['standby', 'busy', 'pending'];

package/crew/routing-fallback.js

@@ -0,0 +1,64 @@
+/**
+ * task-330b — Single fallback-target resolver (Final Spec §B item 3).
+ *
+ * Replaces ad-hoc `session.decisionMaker` lookups scattered across
+ * routing.js / role-output.js / human-interaction.js when a message has
+ * nowhere obvious to go. Centralising this in ONE function lets us:
+ *
+ *   - test the fallback policy in isolation
+ *   - add per-reason policy without touching every call site
+ *   - keep the §B `recordRoutingEvent` calls right next to the decision
+ *
+ * Policy (mirrors what the codebase already does — this is a refactor,
+ * not a behaviour change for the existing 4 reasons):
+ *
+ *   missing-route     → PM (decisionMaker) IF caller is non-PM AND has
+ *                       active task or routing intent. Else: pending (null).
+ *                       PM-no-auto-forward rule (§B item 2): if caller IS
+ *                       PM → ALWAYS pending (null), even with active task.
+ *   parse-fail        → PM (decisionMaker)
+ *   self-route        → null (rejected; §A handles, §B only logs)
+ *   state-stopped     → null (let session.status block the dispatch)
+ *   fallback-forward  → PM (decisionMaker) — explicit auto-forward path
+ *
+ * Returns the target role NAME, or null when "do nothing / pending".
+ *
+ * @param {object} session — crew session (.decisionMaker, .roles)
+ * @param {string} fromRole
+ * @param {string} reason — one of ROUTING_REASONS
+ * @param {object} [opts]
+ * @param {boolean} [opts.hasActiveTask]
+ * @param {boolean} [opts.hasRouteIntent]
+ * @returns {string|null}
+ */
+export function resolveFallbackTarget(session, fromRole, reason, opts = {}) {
+  if (!session) return null;
+  const dm = session.decisionMaker || null;
+
+  switch (reason) {
+    case 'missing-route': {
+      // PM-no-auto-forward rule (§B item 2): PM never auto-forwards to
+      // itself. Returning null signals "park as pending, wait for human".
+      if (fromRole === dm) return null;
+      // Non-PM: only auto-forward when there is something to forward
+      // (active task OR detected routing intent in the prose).
+      if (opts.hasActiveTask || opts.hasRouteIntent) return dm;
+      return null;
+    }
+    case 'parse-fail':
+      // Parser found a ROUTE block but couldn't read it — PM should see
+      // the malformed output to decide next step.
+      return dm;
+    case 'self-route':
+      // §A rejects self-routing; §B records, no fallback dispatch.
+      return null;
+    case 'state-stopped':
+      // Session is stopped/paused; routing must not auto-resume here.
+      return null;
+    case 'fallback-forward':
+      // Explicit safety net (the rename of the existing auto-forward).
+      return dm;
+    default:
+      return null;
+  }
+}

package/crew/routing-metrics.js

@@ -0,0 +1,215 @@
+/**
+ * task-330b — Routing metrics counter (Final Spec §B).
+ *
+ * Centralised observability for crew routing fallbacks. Five canonical
+ * reasons that any fallback path MUST pass to `recordRoutingEvent`:
+ *
+ *   - missing-route     : turn ended with no parseable ROUTE block
+ *   - parse-fail        : ROUTE block found but parse returned null/invalid
+ *   - self-route        : route.to resolves to the sender (rejected by §A)
+ *   - state-stopped     : message arrived while session was stopped/paused
+ *                         and was diverted/dropped
+ *   - fallback-forward  : auto-forward path engaged (non-PM → PM safety net)
+ *
+ * Counters are kept in-memory keyed by `${sessionId}::${reason}` and flushed
+ * to `${sharedDir}/context/routing-metrics.json` periodically (default 30s)
+ * AND on demand via `flushRoutingMetricsNow(session)`. The on-disk format:
+ *
+ *   {
+ *     "schemaVersion": 1,
+ *     "lastFlushedAt": <ms>,
+ *     "counts": {
+ *       "missing-route": 4,
+ *       "parse-fail": 1,
+ *       "self-route": 0,
+ *       "state-stopped": 2,
+ *       "fallback-forward": 4
+ *     },
+ *     "recent": [
+ *       { ts, reason, fromRole, toRole?, taskId?, note? },
+ *       ...                                  // bounded ring buffer (50)
+ *     ]
+ *   }
+ *
+ * Red lines (§330b):
+ *   - Pure observer; never mutates routing decisions.
+ *   - Never throws; failures degrade to console.warn so callers can rely on
+ *     `recordRoutingEvent()` being safe inside hot paths.
+ *
+ * Red lines (§330a — shared with this PR):
+ *   - No engine state-machine touch.
+ *   - PM-self-loop is the responsibility of §A; §B only records the metric
+ *     when §A rejects.
+ */
+
+import { promises as fs } from 'fs';
+import { join } from 'path';
+
+export const ROUTING_REASONS = Object.freeze([
+  'missing-route',
+  'parse-fail',
+  'self-route',
+  'state-stopped',
+  'fallback-forward',
+]);
+
+const REASON_SET = new Set(ROUTING_REASONS);
+const RECENT_RING_SIZE = 50;
+const FLUSH_INTERVAL_MS = 30_000;
+
+/**
+ * In-process state — ONE bag per process. Keyed by sessionId so multiple
+ * crew sessions running in the same agent each keep their own counts.
+ *
+ * Shape: Map<sessionId, {
+ *   sharedDir: string,
+ *   counts: Record<reason, number>,
+ *   recent: Array<{ ts, reason, fromRole, toRole?, taskId?, note? }>,
+ *   dirty: boolean,
+ *   flushTimer: NodeJS.Timeout | null,
+ * }>
+ */
+const _state = new Map();
+
+function _zeroCounts() {
+  const c = {};
+  for (const r of ROUTING_REASONS) c[r] = 0;
+  return c;
+}
+
+function _getOrInit(session) {
+  const sid = session?.id;
+  if (!sid) return null;
+  let bag = _state.get(sid);
+  if (!bag) {
+    bag = {
+      sharedDir: session.sharedDir || null,
+      counts: _zeroCounts(),
+      recent: [],
+      dirty: false,
+      flushTimer: null,
+    };
+    _state.set(sid, bag);
+  }
+  // sharedDir may not be available at session creation — keep latest.
+  if (session.sharedDir) bag.sharedDir = session.sharedDir;
+  return bag;
+}
+
+/**
+ * Record a routing fallback event.
+ *
+ * @param {object} session — crew session (must have .id; .sharedDir for flush)
+ * @param {string} reason — one of ROUTING_REASONS
+ * @param {object} [meta]
+ * @param {string} [meta.fromRole]
+ * @param {string} [meta.toRole]
+ * @param {string} [meta.taskId]
+ * @param {string} [meta.note]
+ * @returns {boolean} true if recorded; false if invalid input
+ */
+export function recordRoutingEvent(session, reason, meta = {}) {
+  if (!session || !session.id) return false;
+  if (!REASON_SET.has(reason)) {
+    console.warn(`[routing-metrics] Unknown reason: ${reason} (allowed: ${ROUTING_REASONS.join(', ')})`);
+    return false;
+  }
+  const bag = _getOrInit(session);
+  if (!bag) return false;
+
+  bag.counts[reason] = (bag.counts[reason] || 0) + 1;
+  bag.recent.push({
+    ts: Date.now(),
+    reason,
+    fromRole: meta.fromRole || null,
+    toRole: meta.toRole || null,
+    taskId: meta.taskId || null,
+    note: meta.note || null,
+  });
+  // Bound the ring.
+  if (bag.recent.length > RECENT_RING_SIZE) {
+    bag.recent.splice(0, bag.recent.length - RECENT_RING_SIZE);
+  }
+  bag.dirty = true;
+  _ensureTimer(session.id, bag);
+  return true;
+}
+
+function _ensureTimer(sessionId, bag) {
+  if (bag.flushTimer) return;
+  bag.flushTimer = setTimeout(() => {
+    bag.flushTimer = null;
+    _flush(sessionId, bag).catch((e) =>
+      console.warn(`[routing-metrics] periodic flush failed for ${sessionId}: ${e.message}`),
+    );
+  }, FLUSH_INTERVAL_MS);
+  // Don't keep the event loop alive solely for metrics flush.
+  if (typeof bag.flushTimer.unref === 'function') bag.flushTimer.unref();
+}
+
+async function _flush(sessionId, bag) {
+  if (!bag.dirty) return;
+  if (!bag.sharedDir) return; // can't flush without target dir
+  const dir = join(bag.sharedDir, 'context');
+  const file = join(dir, 'routing-metrics.json');
+  const payload = {
+    schemaVersion: 1,
+    lastFlushedAt: Date.now(),
+    counts: { ...bag.counts },
+    recent: bag.recent.slice(),
+  };
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    // Write-then-rename for atomicity (single-line file is small; tolerate
+    // platform quirks).
+    const tmp = `${file}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(payload, null, 2), 'utf8');
+    await fs.rename(tmp, file);
+    bag.dirty = false;
+  } catch (e) {
+    console.warn(`[routing-metrics] flush write failed: ${e.message}`);
+  }
+}
+
+/**
+ * Force a synchronous-ish flush (still returns a Promise). Useful from
+ * shutdown paths or tests.
+ */
+export async function flushRoutingMetricsNow(session) {
+  const bag = _state.get(session?.id);
+  if (!bag) return;
+  if (bag.flushTimer) {
+    clearTimeout(bag.flushTimer);
+    bag.flushTimer = null;
+  }
+  await _flush(session.id, bag);
+}
+
+/**
+ * Read current counts (test/inspection only; non-mutating snapshot).
+ * @returns {{ counts: Record<string, number>, recent: Array<object> } | null}
+ */
+export function getRoutingMetricsSnapshot(session) {
+  const bag = _state.get(session?.id);
+  if (!bag) return null;
+  return {
+    counts: { ...bag.counts },
+    recent: bag.recent.slice(),
+  };
+}
+
+/**
+ * Reset (test-only).
+ */
+export function _resetRoutingMetricsForTest(sessionId) {
+  if (sessionId) {
+    const bag = _state.get(sessionId);
+    if (bag?.flushTimer) clearTimeout(bag.flushTimer);
+    _state.delete(sessionId);
+    return;
+  }
+  for (const [, bag] of _state) {
+    if (bag.flushTimer) clearTimeout(bag.flushTimer);
+  }
+  _state.clear();
+}

package/crew/routing.js

@@ -1,12 +1,24 @@
 /**
  * Crew — 路由解析与执行
  * parseRoutes, executeRoute, buildRoutePrompt, dispatchToRole
+ *
+ * task-330c — Greedy-strip guard:
+ *   ⚠️ ROUTE-block stripping lives in `parseRoutes()` ONLY. Callers that
+ *      want the role's prose without ROUTE blocks must consume
+ *      `parseRoutes(text).displayBody` — never run a second
+ *      `text.replace(/---ROUTE---[\s\S]*$/g, '')` style strip on already
+ *      parser-cleaned text. A second strip would (a) re-process text
+ *      that no longer has ROUTE markers (no-op at best, miscut at worst),
+ *      (b) reintroduce the greedy tail-eating bug fixed by task-328.
+ *      The summary-fallback in role-output.js and the recent-routes
+ *      injector below both honour this contract.
  */
 import { join } from 'path';
 import { sendCrewMessage, sendCrewOutput, sendStatusUpdate } from './ui-messages.js';
 import { ensureTaskFile, appendTaskRecord, readTaskFile, updateKanban, readKanban, saveRoleWorkSummary } from './task-files.js';
 import { createRoleQuery, clearRoleSessionId } from './role-query.js';
 import { saveSessionMeta } from './persistence.js';
+import { recordRoutingEvent } from './routing-metrics.js';
 import ctx from '../context.js';
 
 /** Format role label */
@@ -14,6 +26,54 @@ function roleLabel(r) {
   return r.icon ? `${r.icon} ${r.displayName}` : r.displayName;
 }
 
+/**
+ * task-330c — Smart truncate for recent-routes / history snippets.
+ *
+ * Cuts at a sentence/line boundary when possible to avoid mid-sentence
+ * truncation; falls back to a hard cut when no good boundary exists in
+ * the candidate window. Always appends a marker so downstream readers
+ * (LLM roles seeing recent-routes context) know the full text lives
+ * elsewhere (feature file).
+ *
+ * Boundary detection: looks for the last period (`.` `。` `!` `?` `！` `？`)
+ * or newline inside the window `[Math.floor(max*0.7), max)`. The 70% lower
+ * bound is a quality floor — we don't want to cut so early that we lose
+ * meaningful tail context just to hit a clean boundary.
+ *
+ * Idempotent: text already short enough is returned unchanged (no marker).
+ *
+ * @param {string} text — input string (may be any length)
+ * @param {number} max  — maximum chars before truncation
+ * @returns {string}    — original text or `<truncated>…(truncated, full in feature file)`
+ */
+const TRUNCATE_MARKER = '…(truncated, full in feature file)';
+export function smartTruncate(text, max) {
+  if (typeof text !== 'string') return '';
+  if (!Number.isFinite(max) || max <= 0) return '';
+  if (text.length <= max) return text;
+
+  // Search window: prefer cuts in the last 30% of the limit.
+  const windowStart = Math.floor(max * 0.7);
+  const windowSlice = text.slice(windowStart, max);
+  // Last sentence boundary in window — period family OR newline.
+  // We accept a boundary char and cut AFTER it so the sentence stays whole.
+  const BOUNDARY_RE = /[.。!?！？\n]/g;
+  let bestIdx = -1;
+  let m;
+  while ((m = BOUNDARY_RE.exec(windowSlice)) !== null) {
+    bestIdx = m.index;
+  }
+  let cutEnd;
+  if (bestIdx !== -1) {
+    cutEnd = windowStart + bestIdx + 1; // include the boundary char itself
+  } else {
+    cutEnd = max; // no boundary in window → hard cut
+  }
+  // Trim trailing whitespace from the cut piece for cleaner output.
+  const head = text.slice(0, cutEnd).replace(/\s+$/, '');
+  return `${head}${TRUNCATE_MARKER}`;
+}
+
 /**
  * Append text to content — works for both string and multimodal array content.
  * For arrays, appends to the last text block (or adds a new one).
@@ -416,6 +476,77 @@ export function resolveRoleName(to, session, fromRole) {
 export async function executeRoute(session, fromRole, route, turnImages = []) {
   let { to, summary, taskId, taskTitle } = route;
 
+  // ─── task-330a §A + task-330b §B: self-route hard-reject + metric ───
+  // 福勒 Final Spec §A — `route.to` 等同于发送方时直接拒绝，不消费 turn、
+  // 不写 kanban、不 dispatch、不 round++（round 已由 role-output 计数）。
+  // 解析顺序：先尝试用 resolveRoleName 还原 alias（pm/dev/displayName/
+  // pm-乔布斯 等），命中即比较；未命中则退回原始字符串大小写不敏感比较。
+  // 拒绝时：先写 330b 的 routing-metrics.json 持久化 metric（observer 路径），
+  // 再 emit 330a 的 sendCrewMessage UI 卡片，最后 return（不消费 turn）。
+  // alias self-route 漏记 metric 已记入 PM backlog 作 follow-up（330b 的
+  // raw 比较 `to === fromRole` 仅命中字面相同的情况；alias 形式由 330a
+  // 的 isSelf 兜底，但 330b 的 raw 检查保留为快速路径 + 兼容）。
+  if (to !== 'human') {
+    const resolvedSelfCheck = resolveRoleName(to, session, fromRole);
+    const isSelf = resolvedSelfCheck === fromRole
+      || (typeof to === 'string' && to.toLowerCase() === String(fromRole).toLowerCase());
+    if (isSelf) {
+      console.warn(`[Crew] Self-route rejected: ${fromRole} → ${to} (taskId=${taskId || '-'})`);
+      // 330b path — persistent metric counter (routing-metrics.json + ring).
+      // Always-safe; never throws (recordRoutingEvent degrades to console.warn).
+      recordRoutingEvent(session, 'self-route', {
+        fromRole,
+        toRole: to,
+        taskId: taskId || null,
+        note: 'route.to === fromRole at executeRoute entry (rejected by §A)',
+      });
+      // 330a path — UI broadcast so the role sees rejection in transcript.
+      try {
+        sendCrewMessage({
+          type: 'routing-metrics',
+          sessionId: session.id,
+          event: 'route_rejected',
+          reason: 'self-route',
+          fromRole,
+          to,
+          taskId: taskId || null,
+          timestamp: Date.now(),
+        });
+      } catch (e) {
+        console.warn('[Crew] Failed to emit routing-metrics:', e.message);
+      }
+      try {
+        sendCrewMessage({
+          type: 'crew_route_rejected',
+          sessionId: session.id,
+          fromRole,
+          to,
+          reason: 'self-route',
+          message: `自路由被拒绝：${fromRole} 不能给自己发消息。请改用 task_close(taskId, summary) 关闭任务，或 role_standby(role) 进入待命，或选择其他角色作为 ROUTE 目标。`,
+          taskId: taskId || null,
+        });
+      } catch (e) {
+        console.warn('[Crew] Failed to emit crew_route_rejected:', e.message);
+      }
+      // Do NOT decrement session.round — role-output.js already incremented
+      // it for this whole turn batch; one rejected route doesn't undo the
+      // turn (other routes in the same batch may still be valid).
+      return;
+    }
+  }
+
+  // task-330b §B item 1: state-stopped metric — message arrived while
+  // session was paused/stopped. Behaviour (auto-resume) is unchanged for
+  // backward compat; this is observer-only.
+  if (session.status === 'paused' || session.status === 'stopped') {
+    recordRoutingEvent(session, 'state-stopped', {
+      fromRole,
+      toRole: to,
+      taskId: taskId || null,
+      note: `session.status=${session.status} at executeRoute entry`,
+    });
+  }
+
   // Auto-resume: paused/stopped → running (route execution means work should continue)
   if (session.status === 'paused' || session.status === 'stopped') {
     console.log(`[Crew] Auto-resuming session from ${session.status} to running (route from ${fromRole} to ${to})`);
@@ -620,11 +751,21 @@ export async function dispatchToRole(session, roleName, content, fromSource, tas
   }
 
   // 最近路由消息注入（帮助 clear 后的角色恢复上下文）
+  // task-330c: each entry is smart-truncated to 400 chars at a sentence
+  // boundary (period/newline) so we don't slice key info mid-sentence.
+  // The full content lives in the feature file — the marker tells the
+  // role where to look if they need more context. The pre-stored
+  // `m.content` was already truncated to 200 (history step below) until
+  // task-330c bumped it to 400 + smart boundary.
+  // ⚠️ DO NOT pass `m.content` through any greedy `.replace(/.../g, '')`
+  //    here — it has already been derived from displayBody at message
+  //    time (parser-stripped), and a second strip would re-process
+  //    text that no longer holds ROUTE markers. See _appendHistory below.
   if (session.messageHistory.length > 0) {
     const recentRoutes = session.messageHistory
       .filter(m => m.from !== 'system')
       .slice(-5)
-      .map(m => `[${m.from} → ${m.to}${m.taskId ? ` (${m.taskId})` : ''}] ${m.content}`)
+      .map(m => `[${m.from} → ${m.to}${m.taskId ? ` (${m.taskId})` : ''}] ${smartTruncate(m.content, 400)}`)
       .join('\n');
     if (recentRoutes) {
       const ctx = `\n\n---\n<recent-routes>\n${recentRoutes}\n</recent-routes>`;
@@ -633,9 +774,15 @@ export async function dispatchToRole(session, roleName, content, fromSource, tas
   }
 
   // 记录消息历史
+  // task-330c: cap raised 200 → 400 to match the recent-routes injection
+  // window. Keeping the pre-store cap at 200 would pin every entry below
+  // smartTruncate's 400 threshold, making the smart-truncate boundary cut
+  // a permanent no-op in production. 400 here lets longer messages flow
+  // into history; smartTruncate trims them at sentence boundaries when
+  // injected into <recent-routes>.
   const historyContent = typeof content === 'string'
-    ? content.substring(0, 200)
-    : (Array.isArray(content) ? content.filter(b => b.type === 'text').map(b => b.text).join('').substring(0, 200) + (content.some(b => b.type === 'image') ? ' [+images]' : '') : '...');
+    ? content.substring(0, 400)
+    : (Array.isArray(content) ? content.filter(b => b.type === 'text').map(b => b.text).join('').substring(0, 400) + (content.some(b => b.type === 'image') ? ' [+images]' : '') : '...');
   session.messageHistory.push({
     from: fromSource,
     to: roleName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.510",
+  "version": "0.1.511",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/web-bridge.js

@@ -11,6 +11,15 @@
  *   3. Engine.query() yields events → translated into unify_output messages
  *      that carry { conversationId, data } in claude_output format.
  *   4. The frontend's handleUnifyOutput dispatches them through handleClaudeOutput.
+ *
+ * task-330c lint guard:
+ *   ⚠️ DO NOT introduce greedy `text.replace(/---ROUTE---[\s\S]*$/g, '')`
+ *      style strips on incoming/outgoing message bodies. Crew ROUTE
+ *      stripping is owned EXCLUSIVELY by `agent/crew/routing.js`
+ *      `parseRoutes()` which returns `{routes, displayBody}` with exact
+ *      ranges removed. Re-stripping here would (a) double-eat content
+ *      that has already been parser-cleaned, (b) reintroduce the bug
+ *      task-328 fixed (greedy tail-strip ate trailing prose).
  */
 
 import { loadSession } from './session.js';