@teamclaws/teamclaw 2026.3.25 → 2026.3.26-1

package/index.ts

@@ -1,6 +1,6 @@
 import { definePluginEntry, type OpenClawPluginApi } from "./api.js";
 import { parsePluginConfig } from "./src/types.js";
-import type { TaskExecutionEventInput, WorkerIdentity } from "./src/types.js";
+import type { TaskAssignmentPayload, TaskExecutionEventInput, TeamState, WorkerIdentity } from "./src/types.js";
 import { buildConfigSchema } from "./src/config.js";
 import { loadTeamState } from "./src/state.js";
 import { createRoleTaskExecutor } from "./src/task-executor.js";
@@ -39,9 +39,18 @@ function registerController(api: OpenClawPluginApi, config: ReturnType<typeof pa
     logger,
     runtime: api.runtime,
   });
+  let getControllerTeamState = (): TeamState | null => null;
 
   // Service (starts HTTP server + mDNS + WebSocket)
-  api.registerService(createControllerService({ config, logger, runtime: api.runtime, localWorkerManager }));
+  api.registerService(createControllerService({
+    config,
+    logger,
+    runtime: api.runtime,
+    localWorkerManager,
+    onTeamStateAvailable: (getter) => {
+      getControllerTeamState = getter;
+    },
+  }));
 
   // Prompt injection
   api.on("before_prompt_build", async (_event: unknown, ctx: { sessionKey?: string | null }) => {
@@ -56,7 +65,7 @@ function registerController(api: OpenClawPluginApi, config: ReturnType<typeof pa
       return injector() ?? {};
     }
 
-    const state = await loadTeamState(config.teamName);
+    const state = getControllerTeamState() ?? await loadTeamState(config.teamName);
     const injector = createControllerPromptInjector({
       config,
       getTeamState: () => state,
@@ -78,7 +87,8 @@ function registerController(api: OpenClawPluginApi, config: ReturnType<typeof pa
     return createControllerTools({
       config,
       controllerUrl,
-      getTeamState: () => null,
+      getTeamState: getControllerTeamState,
+      sessionKey: ctx.sessionKey ?? null,
     });
   });
 }
@@ -122,7 +132,8 @@ function registerWorker(api: OpenClawPluginApi, config: ReturnType<typeof parseP
     }
   }
 
-  const getWorkerSessionKey = (taskId: string) => `teamclaw-task-${taskId}`;
+  const getWorkerSessionKey = (assignment: TaskAssignmentPayload) =>
+    assignment.executionSessionKey?.trim() || `teamclaw-task-${assignment.taskId}`;
 
   const taskExecutor = createRoleTaskExecutor({
     runtime: api.runtime,
@@ -130,7 +141,8 @@ function registerWorker(api: OpenClawPluginApi, config: ReturnType<typeof parseP
     role: config.role,
     taskTimeoutMs: config.taskTimeoutMs,
     getSessionKey: getWorkerSessionKey,
-    getIdempotencyKey: (taskId) => `teamclaw-${taskId}`,
+    getIdempotencyKey: (assignment) =>
+      assignment.executionIdempotencyKey?.trim() || `teamclaw-${assignment.taskId}`,
     reportExecutionEvent,
   });
 
@@ -144,6 +156,7 @@ function registerWorker(api: OpenClawPluginApi, config: ReturnType<typeof parseP
         currentWorkerId = identity.workerId;
       },
       prepareTaskAssignment: async (assignment) => {
+        const controllerUrl = currentControllerUrl || config.controllerUrl.trim();
         if (assignment.recommendedSkills?.length) {
           try {
             const skillInstall = await installRecommendedSkills(assignment, logger);
@@ -163,7 +176,7 @@ function registerWorker(api: OpenClawPluginApi, config: ReturnType<typeof parseP
           }
         }
 
-        if (!assignment.repo?.enabled || !currentControllerUrl) {
+        if (!assignment.repo?.enabled || !controllerUrl) {
           return;
         }
 
@@ -176,7 +189,7 @@ function registerWorker(api: OpenClawPluginApi, config: ReturnType<typeof parseP
         });
 
         try {
-          const syncResult = await syncWorkerRepo(config, logger, currentControllerUrl, assignment.repo);
+          const syncResult = await syncWorkerRepo(config, logger, controllerUrl, assignment.repo);
           await reportExecutionEvent(assignment.taskId, {
             type: "lifecycle",
             phase: "repo_sync_completed",
@@ -197,9 +210,11 @@ function registerWorker(api: OpenClawPluginApi, config: ReturnType<typeof parseP
         }
       },
       publishTaskAssignment: async (assignment) => {
-        if (!assignment.repo?.enabled || !currentControllerUrl || !currentWorkerId) {
+        const controllerUrl = currentControllerUrl || config.controllerUrl.trim();
+        if (!assignment.repo?.enabled || !controllerUrl) {
           return;
         }
+        const workerId = currentWorkerId || "unknown-worker";
 
         await reportExecutionEvent(assignment.taskId, {
           type: "lifecycle",
@@ -210,9 +225,9 @@ function registerWorker(api: OpenClawPluginApi, config: ReturnType<typeof parseP
         });
 
         try {
-          const publishResult = await publishWorkerRepo(config, logger, currentControllerUrl, assignment.repo, {
+          const publishResult = await publishWorkerRepo(config, logger, controllerUrl, assignment.repo, {
             taskId: assignment.taskId,
-            workerId: currentWorkerId,
+            workerId,
             role: config.role,
           });
           await reportExecutionEvent(assignment.taskId, {
@@ -235,14 +250,14 @@ function registerWorker(api: OpenClawPluginApi, config: ReturnType<typeof parseP
         }
       },
       taskExecutor,
-      cancelTaskExecution: async (taskId) => {
-        const sessionKey = getWorkerSessionKey(taskId);
+      cancelTaskExecution: async (taskId, sessionKey) => {
+        const resolvedSessionKey = sessionKey || `teamclaw-task-${taskId}`;
         try {
-          await api.runtime.subagent.deleteSession({ sessionKey });
-          logger.info(`Worker: cancelled subagent session ${sessionKey} for task ${taskId}`);
+          await api.runtime.subagent.deleteSession({ sessionKey: resolvedSessionKey });
+          logger.info(`Worker: cancelled subagent session ${resolvedSessionKey} for task ${taskId}`);
           return true;
         } catch (err) {
-          logger.warn(`Worker: failed to cancel session ${sessionKey} for task ${taskId}: ${String(err)}`);
+          logger.warn(`Worker: failed to cancel session ${resolvedSessionKey} for task ${taskId}: ${String(err)}`);
           return false;
         }
       },

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "teamclaw",
   "name": "TeamClaw",
   "description": "Virtual team collaboration - multiple OpenClaw instances form a virtual software company with role-based task routing.",
-  "version": "2026.3.25",
+  "version": "2026.3.26-1",
   "uiHints": {
     "mode": {
       "label": "Mode",
@@ -66,7 +66,7 @@
     },
     "workerProvisioningRoles": {
       "label": "Provisioned Roles",
-      "help": "Only launch these roles on demand; leave empty for all roles"
+      "help": "Preferred on-demand roles; task-required roles can still launch automatically"
     },
     "workerProvisioningMinPerRole": {
       "label": "Warm Workers Per Role",
@@ -243,7 +243,7 @@
       "workerProvisioningRoles": {
         "type": "array",
         "default": [],
-        "description": "Restrict on-demand launches to specific roles; empty means all roles",
+        "description": "Preferred on-demand roles; task-required roles can still launch automatically. Empty means controller-decided defaults across all roles",
         "items": {
           "type": "string",
           "enum": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamclaws/teamclaw",
-  "version": "2026.3.25",
+  "version": "2026.3.26-1",
   "description": "OpenClaw virtual software team orchestration plugin",
   "private": false,
   "keywords": [
@@ -8,8 +8,12 @@
     "plugin",
     "teamclaw",
     "multi-agent",
-    "orchestration"
+    "orchestration",
+    "virtual-team",
+    "sdlc",
+    "multi-role"
   ],
+  "author": "Junjun Zhang <topcheer@me.com>",
   "homepage": "https://github.com/topcheer/teamclaw/tree/main/src#readme",
   "bugs": {
     "url": "https://github.com/topcheer/teamclaw/issues"
@@ -20,8 +24,11 @@
     "directory": "src"
   },
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "bin": {
-    "teamclaw": "./cli.mjs"
+    "teamclaw": "cli.mjs"
   },
   "files": [
     "README.md",
@@ -40,7 +47,7 @@
     "@sinclair/typebox": "0.34.48",
     "bonjour-service": "^1.3.0",
     "json5": "^2.2.3",
-    "openclaw": "2026.3.23-2",
+    "openclaw": "2026.3.24",
     "ws": "^8.19.0"
   },
   "devDependencies": {
@@ -53,6 +60,11 @@
     "extensions": [
       "./index.ts"
     ],
+    "install": {
+      "npmSpec": "@teamclaws/teamclaw",
+      "localPath": "src",
+      "defaultChoice": "npm"
+    },
     "release": {
       "publishToNpm": true
     }

package/src/config.ts

@@ -92,7 +92,7 @@ function buildConfigSchema() {
         workerProvisioningRoles: {
           type: "array" as const,
           default: [],
-          description: "Restrict on-demand launches to specific roles; empty means all roles",
+          description: "Preferred on-demand roles; task-required roles can still launch automatically. Empty means controller-decided defaults across all roles",
           items: {
             type: "string" as const,
             enum: ROLE_IDS,
@@ -245,7 +245,7 @@ function buildConfigSchema() {
       },
       workerProvisioningRoles: {
         label: "Provisioned Roles",
-        help: "Only launch these roles on demand; leave empty for all roles",
+        help: "Preferred on-demand roles; task-required roles can still launch automatically",
       },
       workerProvisioningMinPerRole: {
         label: "Warm Workers Per Role",

package/src/controller/controller-capacity.ts

@@ -0,0 +1,23 @@
+import type { PluginConfig, TeamState } from "../types.js";
+
+export function hasOnDemandWorkerProvisioning(
+  config: Pick<PluginConfig, "workerProvisioningType">,
+): boolean {
+  return config.workerProvisioningType !== "none";
+}
+
+export function shouldBlockControllerWithoutWorkers(
+  config: Pick<PluginConfig, "workerProvisioningType">,
+  state: TeamState | null,
+): boolean {
+  return !!state && Object.keys(state.workers).length === 0 && !hasOnDemandWorkerProvisioning(config);
+}
+
+export function buildControllerNoWorkersMessage(): string {
+  return [
+    "No TeamClaw workers are registered and on-demand provisioning is disabled.",
+    "You may analyze the requirement and identify the roles that would be needed,",
+    "but do not create TeamClaw tasks and do not do the worker-role work yourself.",
+    "Ask the human to bring workers online or enable process/docker/kubernetes provisioning first.",
+  ].join(" ");
+}

package/src/controller/controller-service.ts

@@ -1,4 +1,5 @@
 import type { OpenClawPluginApi, OpenClawPluginService, OpenClawPluginServiceContext, PluginLogger } from "../../api.js";
+import os from "node:os";
 import type { PluginConfig, TeamState } from "../types.js";
 import { loadTeamState, saveTeamState } from "../state.js";
 import { MDnsAdvertiser } from "../discovery.js";
@@ -17,8 +18,27 @@ export type ControllerServiceDeps = {
   logger: PluginLogger;
   runtime: OpenClawPluginApi["runtime"];
   localWorkerManager?: LocalWorkerManager;
+  onTeamStateAvailable?: (getter: () => TeamState | null) => void;
 };
 
+function getPreferredLanUiUrl(port: number): string | null {
+  const candidates: string[] = [];
+  const interfaces = os.networkInterfaces();
+  for (const records of Object.values(interfaces)) {
+    for (const record of records ?? []) {
+      if (!record || record.internal || record.family !== "IPv4") {
+        continue;
+      }
+      candidates.push(record.address);
+    }
+  }
+  candidates.sort((left, right) => left.localeCompare(right));
+  if (candidates.length === 0) {
+    return null;
+  }
+  return `http://${candidates[0]}:${port}/ui`;
+}
+
 export function createControllerService(deps: ControllerServiceDeps): OpenClawPluginService {
   const { config, logger, localWorkerManager } = deps;
   let teamState: TeamState | null = null;
@@ -61,6 +81,7 @@ export function createControllerService(deps: ControllerServiceDeps): OpenClawPl
         repoStateChanged = JSON.stringify(teamState.repo ?? null) !== previousRepoState;
         logger.info(`Controller: restored team "${config.teamName}" with ${Object.keys(teamState.workers).length} workers`);
       }
+      deps.onTeamStateAvailable?.(() => teamState);
 
       const updateState = (updater: (state: TeamState) => void): TeamState => {
         updater(teamState!);
@@ -108,7 +129,11 @@ export function createControllerService(deps: ControllerServiceDeps): OpenClawPl
       await new Promise<void>((resolve, reject) => {
         server.listen(config.port, () => {
           logger.info(`Controller: HTTP server listening on port ${config.port}`);
-          logger.info(`Controller: Web UI available at http://localhost:${config.port}/ui`);
+          logger.info(`Controller: Web UI available at http://127.0.0.1:${config.port}/ui`);
+          const lanUiUrl = getPreferredLanUiUrl(config.port);
+          if (lanUiUrl) {
+            logger.info(`Controller: Web UI available on LAN at ${lanUiUrl}`);
+          }
           resolve();
         });
         server.on("error", reject);
@@ -180,6 +205,7 @@ export function createControllerService(deps: ControllerServiceDeps): OpenClawPl
       }
     },
     async stop() {
+      deps.onTeamStateAvailable?.(() => null);
       if (timeoutTimer) {
         clearInterval(timeoutTimer);
         timeoutTimer = null;

package/src/controller/controller-tools.ts

@@ -1,24 +1,51 @@
 import { Type } from "@sinclair/typebox";
-import type { PluginConfig, TaskInfo, TeamState } from "../types.js";
+import type {
+  ControllerOrchestrationManifest,
+  PluginConfig,
+  TaskInfo,
+  TeamState,
+} from "../types.js";
+import { buildControllerNoWorkersMessage, hasOnDemandWorkerProvisioning, shouldBlockControllerWithoutWorkers } from "./controller-capacity.js";
+import {
+  normalizeManifestCreatedTasks,
+  normalizeManifestDeferredTasks,
+  normalizeManifestRoleList,
+  normalizeManifestStringList,
+  normalizeOptionalManifestText,
+} from "./orchestration-manifest.js";
+import {
+  ensureTeamMessageContract,
+  normalizeContractRole,
+  normalizeContractStringList,
+} from "../interaction-contracts.js";
 
 export type ControllerToolsDeps = {
   config: PluginConfig;
   controllerUrl: string;
   getTeamState: () => TeamState | null;
+  sessionKey?: string | null;
 };
 
 const EXECUTION_READY_BLOCKERS: Array<{ pattern: RegExp; reason: string }> = [
   { pattern: /\bdepends?\s+on\b/i, reason: "it explicitly depends on other unfinished work" },
   { pattern: /\bprerequisite\b/i, reason: "it references a prerequisite that may not be satisfied yet" },
   { pattern: /\bwait(?:ing)?\s+for\b/i, reason: "it says the work should wait for another output first" },
-  { pattern: /\bafter\b.+\b(complete|completed|ready|available|exists?)\b/i, reason: "it is phrased as a later-phase task" },
-  { pattern: /\bonce\b.+\b(complete|completed|ready|available|exists?)\b/i, reason: "it is phrased as a later-phase task" },
-  { pattern: /依赖|前置|前提/u, reason: "it explicitly mentions a predecessor dependency" },
-  { pattern: /完成后|就绪后|待.*完成|等待.*完成/u, reason: "it is described as work for a later phase" },
+  { pattern: /依赖于|前置条件|前置依赖|前提条件|前序任务|上游任务/u, reason: "it explicitly mentions a predecessor dependency" },
+  { pattern: /待.*完成|等待.*完成/u, reason: "it is described as work for a later phase" },
 ];
 
+const ENGLISH_LATER_PHASE_CLAUSE_RE = /\b(?:after|once)\b(.+?)\b(complete|completed|ready|available|exists?)\b/i;
+const ENGLISH_LATER_PHASE_DEPENDENCY_RE = /\b(?:task|tasks|service|services|module|modules|phase|phases|api|apis|interface|interfaces|review|qa|design|developer|architect|skeleton|backend|frontend|deliverable|artifact|handoff)\b/i;
+const CHINESE_LATER_PHASE_CLAUSE_RE = /(.+?)(完成后|就绪后)/u;
+const CHINESE_LATER_PHASE_DEPENDENCY_RE = /(?:服务|模块|任务|阶段|接口|骨架|后端|前端|设计|审查|开发|测试|架构|交付物|文档|交接)/u;
+const SERVICE_NAME_RE = /\b[a-z0-9_-]+-service\b/i;
+const SERVICE_NAME_GLOBAL_RE = /\b[a-z0-9_-]+-service\b/gi;
+const ACTIVE_TASK_STATUSES = new Set(["pending", "assigned", "in_progress", "review", "blocked"]);
+const REPO_WIDE_CODE_CHANGE_RE = /(financial-erp-backend\/|all services|all microservices|all backend services|所有服务|所有微服务|全部微服务|统一.*kafka|kafka topic|db\/migration|schema|ddl|api路径|trusted\.packages|pom\.xml|webmvcconfig|安全响应头)/i;
+const DOC_ONLY_SCOPE_RE = /(文档|docs\/|api design|architecture document|设计文档|报告|report)/i;
+
 export function createControllerTools(deps: ControllerToolsDeps) {
-  const { config, controllerUrl, getTeamState } = deps;
+  const { config, controllerUrl, getTeamState, sessionKey } = deps;
   const baseUrl = controllerUrl;
 
   return [
@@ -42,10 +69,21 @@ export function createControllerTools(deps: ControllerToolsDeps) {
       async execute(_id: string, params: Record<string, unknown>) {
         const title = String(params.title ?? "");
         const description = String(params.description ?? "");
+        const normalizedSessionKey = typeof sessionKey === "string" ? sessionKey.trim() : "";
         if (!title) {
           return { content: [{ type: "text" as const, text: "title is required." }] };
         }
 
+        const state = getTeamState();
+        if (shouldBlockControllerWithoutWorkers(config, state)) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: `${buildControllerNoWorkersMessage()} Stop after reporting this block to the human.`,
+            }],
+          };
+        }
+
         const blocker = detectExecutionReadyBlocker(description);
         if (blocker) {
           return {
@@ -55,6 +93,15 @@ export function createControllerTools(deps: ControllerToolsDeps) {
             }],
           };
         }
+        const overlapBlocker = detectActiveTaskOverlap(title, description, state);
+        if (overlapBlocker) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: `Refusing to create task "${title}" because it is not execution-ready: ${overlapBlocker}. Wait for the active task to finish or narrow the new task so it does not edit the same service scope in parallel.`,
+            }],
+          };
+        }
 
         try {
           const res = await fetch(`${baseUrl}/api/v1/tasks`, {
@@ -67,6 +114,7 @@ export function createControllerTools(deps: ControllerToolsDeps) {
               assignedRole: params.assignedRole ?? undefined,
               recommendedSkills: Array.isArray(params.recommendedSkills) ? params.recommendedSkills : undefined,
               createdBy: "controller",
+              controllerSessionKey: normalizedSessionKey || undefined,
             }),
           });
 
@@ -80,7 +128,9 @@ export function createControllerTools(deps: ControllerToolsDeps) {
           const assigned = task.assignedWorkerId
             ? ` -> assigned to ${task.assignedWorkerId}`
             : task.status === "pending"
-              ? " (pending - no available worker)"
+              ? hasOnDemandWorkerProvisioning(config)
+                ? " (pending - waiting for worker provisioning or an available worker)"
+                : " (pending - no registered/available worker)"
               : "";
           const recommended = Array.isArray(task.recommendedSkills) && task.recommendedSkills.length > 0
             ? ` | skills: ${task.recommendedSkills.join(", ")}`
@@ -97,6 +147,97 @@ export function createControllerTools(deps: ControllerToolsDeps) {
         }
       },
     },
+    {
+      name: "teamclaw_submit_manifest",
+      label: "Submit Controller Manifest",
+      description: "Record the structured orchestration manifest for this intake run after role selection and task creation decisions are complete",
+      parameters: Type.Object({
+        requirementSummary: Type.String({ description: "Brief summary of the requirement the controller is orchestrating" }),
+        requiredRoles: Type.Array(
+          Type.String({
+            description: "Exact TeamClaw role IDs required for this requirement",
+          }),
+        ),
+        clarificationsNeeded: Type.Optional(Type.Boolean({ description: "Whether the controller still needs human clarification" })),
+        clarificationQuestions: Type.Optional(
+          Type.Array(Type.String({ description: "Concrete clarification questions still waiting on the human" })),
+        ),
+        createdTasks: Type.Optional(
+          Type.Array(
+                Type.Object({
+                  title: Type.String({ description: "Title of an execution-ready task this controller run created or deliberately reused instead of duplicating" }),
+                  assignedRole: Type.Optional(Type.String({ description: "Exact TeamClaw role ID for the created task" })),
+                  expectedOutcome: Type.String({ description: "Expected deliverable/result for the created task" }),
+                }),
+              ),
+            ),
+        deferredTasks: Type.Optional(
+          Type.Array(
+            Type.Object({
+              title: Type.String({ description: "Title of a task that should wait for later" }),
+              assignedRole: Type.Optional(Type.String({ description: "Exact TeamClaw role ID for the deferred task" })),
+              blockedBy: Type.String({ description: "Why this deferred task cannot be created yet" }),
+              whenReady: Type.String({ description: "Condition that should become true before this deferred task is created" }),
+            }),
+          ),
+        ),
+        handoffPlan: Type.Optional(Type.String({ description: "Brief note about how workers should report progress/handoffs across this flow" })),
+        notes: Type.Optional(Type.String({ description: "Additional orchestration notes for the human/controller log" })),
+      }),
+      async execute(_id: string, params: Record<string, unknown>) {
+        const normalizedSessionKey = typeof sessionKey === "string" ? sessionKey.trim() : "";
+        if (!normalizedSessionKey) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: "Cannot record controller manifest because the current TeamClaw controller session key is missing.",
+            }],
+          };
+        }
+
+        const requirementSummary = String(params.requirementSummary ?? "").trim();
+        if (!requirementSummary) {
+          return { content: [{ type: "text" as const, text: "requirementSummary is required." }] };
+        }
+
+        const manifest: ControllerOrchestrationManifest = {
+          version: "1.0",
+          requirementSummary,
+          requiredRoles: normalizeManifestRoleList(params.requiredRoles),
+          clarificationsNeeded: Boolean(params.clarificationsNeeded),
+          clarificationQuestions: normalizeManifestStringList(params.clarificationQuestions),
+          createdTasks: normalizeManifestCreatedTasks(params.createdTasks),
+          deferredTasks: normalizeManifestDeferredTasks(params.deferredTasks),
+          handoffPlan: normalizeOptionalManifestText(params.handoffPlan),
+          notes: normalizeOptionalManifestText(params.notes),
+        };
+
+        try {
+          const res = await fetch(`${baseUrl}/api/v1/controller/manifest`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              sessionKey: normalizedSessionKey,
+              manifest,
+            }),
+          });
+
+          if (!res.ok) {
+            const err = await res.text();
+            return { content: [{ type: "text" as const, text: `Failed to record controller manifest: ${err}` }] };
+          }
+
+          return {
+            content: [{
+              type: "text" as const,
+              text: `Controller manifest recorded: roles=${manifest.requiredRoles.join(", ") || "none"} created=${manifest.createdTasks.length} deferred=${manifest.deferredTasks.length}`,
+            }],
+          };
+        } catch (err) {
+          return { content: [{ type: "text" as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+      },
+    },
     {
       name: "teamclaw_list_tasks",
       label: "List Team Tasks",
@@ -177,6 +318,11 @@ export function createControllerTools(deps: ControllerToolsDeps) {
         content: Type.String({ description: "Message content" }),
         toRole: Type.Optional(Type.String({ description: "Target role for direct message (omit for broadcast)" })),
         taskId: Type.Optional(Type.String({ description: "Related task ID" })),
+        summary: Type.Optional(Type.String({ description: "Short structured summary for this coordination message" })),
+        details: Type.Optional(Type.String({ description: "Optional extra context for the receiving worker(s)" })),
+        requestedAction: Type.Optional(Type.String({ description: "Concrete action expected after reading the message" })),
+        needsResponse: Type.Optional(Type.Boolean({ description: "Whether this message expects a direct response" })),
+        references: Type.Optional(Type.Array(Type.String({ description: "Relevant task IDs, files, or artifacts" }))),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
         const content = String(params.content ?? "");
@@ -185,14 +331,28 @@ export function createControllerTools(deps: ControllerToolsDeps) {
         }
 
         try {
+          const normalizedTargetRole = normalizeContractRole(params.toRole);
           const endpoint = params.toRole
             ? `${baseUrl}/api/v1/messages/direct`
             : `${baseUrl}/api/v1/messages/broadcast`;
+          const contract = ensureTeamMessageContract(null, {
+            type: params.toRole ? "direct" : "broadcast",
+            content,
+            toRole: normalizedTargetRole,
+            taskId: typeof params.taskId === "string" ? params.taskId : undefined,
+            summary: typeof params.summary === "string" ? params.summary : undefined,
+            details: typeof params.details === "string" ? params.details : undefined,
+            requestedAction: typeof params.requestedAction === "string" ? params.requestedAction : undefined,
+            needsResponse: typeof params.needsResponse === "boolean" ? params.needsResponse : undefined,
+            references: normalizeContractStringList(params.references),
+            intent: params.toRole ? undefined : "announcement",
+          });
 
           const body: Record<string, unknown> = {
             from: "controller",
             content,
             taskId: params.taskId ?? null,
+            contract,
           };
           if (params.toRole) body.toRole = params.toRole;
 
@@ -231,5 +391,89 @@ function detectExecutionReadyBlocker(description: string): string | null {
     }
   }
 
+  const laterPhaseBlocker = detectLaterPhasePhrase(text);
+  if (laterPhaseBlocker) {
+    return laterPhaseBlocker;
+  }
+
   return null;
 }
+
+function detectLaterPhasePhrase(text: string): string | null {
+  const lines = text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  for (const line of lines) {
+    const englishMatch = line.match(ENGLISH_LATER_PHASE_CLAUSE_RE);
+    if (englishMatch) {
+      const dependencyClause = englishMatch[1] ?? "";
+      if (ENGLISH_LATER_PHASE_DEPENDENCY_RE.test(dependencyClause) || SERVICE_NAME_RE.test(dependencyClause)) {
+        return "it is described as work for a later phase";
+      }
+    }
+
+    const chineseMatch = line.match(CHINESE_LATER_PHASE_CLAUSE_RE);
+    if (chineseMatch) {
+      const dependencyClause = chineseMatch[1] ?? "";
+      if (CHINESE_LATER_PHASE_DEPENDENCY_RE.test(dependencyClause) || SERVICE_NAME_RE.test(dependencyClause)) {
+        return "it is described as work for a later phase";
+      }
+    }
+  }
+
+  return null;
+}
+
+function detectActiveTaskOverlap(title: string, description: string, state: TeamState | null): string | null {
+  if (!state) {
+    return null;
+  }
+  const scopeText = `${title}\n${description}`;
+  const serviceNames = extractServiceNames(scopeText);
+  const repoWideCodeChange = serviceNames.size === 0
+    && REPO_WIDE_CODE_CHANGE_RE.test(scopeText)
+    && !DOC_ONLY_SCOPE_RE.test(scopeText);
+  if (serviceNames.size === 0 && !repoWideCodeChange) {
+    return null;
+  }
+
+  const overlappingTasks = Object.values(state.tasks).filter((task) => {
+    if (!ACTIVE_TASK_STATUSES.has(task.status)) {
+      return false;
+    }
+    const taskScope = `${task.title}\n${task.description}`;
+    const taskServiceNames = extractServiceNames(taskScope);
+    if (serviceNames.size > 0) {
+      return [...serviceNames].some((serviceName) => taskServiceNames.has(serviceName));
+    }
+    if (taskServiceNames.size > 0) {
+      return true;
+    }
+    return REPO_WIDE_CODE_CHANGE_RE.test(taskScope) && !DOC_ONLY_SCOPE_RE.test(taskScope);
+  });
+  if (overlappingTasks.length === 0) {
+    return null;
+  }
+
+  const overlappingServices = new Set<string>();
+  for (const task of overlappingTasks) {
+    for (const serviceName of extractServiceNames(`${task.title}\n${task.description}`)) {
+      overlappingServices.add(serviceName);
+    }
+  }
+  if (overlappingServices.size > 0) {
+    return `it overlaps with active TeamClaw work on ${[...overlappingServices].slice(0, 3).join(", ")}`;
+  }
+  return `it overlaps with active TeamClaw repo-wide code changes (${overlappingTasks[0]?.title ?? "another active task"})`;
+}
+
+function extractServiceNames(text: string): Set<string> {
+  const normalized = String(text || "");
+  return new Set(
+    Array.from(normalized.matchAll(SERVICE_NAME_GLOBAL_RE))
+      .map((match) => String(match[0] || "").trim().toLowerCase())
+      .filter(Boolean),
+  );
+}