@teamclaws/teamclaw 2026.3.25 → 2026.3.26-1

package/src/controller/http-server.ts

@@ -5,6 +5,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawPluginApi, PluginLogger } from "../../api.js";
 import type {
   ClarificationRequest,
+  ControllerOrchestrationManifest,
   ControllerRunInfo,
   ControllerRunSource,
   GitRepoState,
@@ -21,7 +22,9 @@ import type {
   TaskStatus,
   TeamMessage,
   TeamState,
+  WorkerProgressContract,
   WorkerInfo,
+  WorkerTaskResultContract,
 } from "../types.js";
 import {
   parseJsonBody,
@@ -38,6 +41,17 @@ import { TaskRouter } from "./task-router.js";
 import { MessageRouter } from "./message-router.js";
 import { TeamWebSocketServer } from "./websocket.js";
 import type { WorkerProvisioningManager } from "./worker-provisioning.js";
+import { createControllerPromptInjector } from "./prompt-injector.js";
+import { buildControllerNoWorkersMessage, shouldBlockControllerWithoutWorkers } from "./controller-capacity.js";
+import {
+  backfillWorkerProgressContract,
+  backfillWorkerTaskResultContract,
+  ensureTeamMessageContract,
+  normalizeTaskHandoffContract,
+  normalizeWorkerProgressContract,
+  normalizeWorkerTaskResultContract,
+} from "../interaction-contracts.js";
+import { normalizeControllerManifest } from "./orchestration-manifest.js";
 
 export type ControllerHttpDeps = {
   config: PluginConfig;
@@ -56,8 +70,23 @@ const MAX_TASK_EXECUTION_EVENTS = 250;
 const MAX_CONTROLLER_RUNS = 40;
 const MAX_RECENT_TASK_CONTEXT = 3;
 const MAX_TASK_CONTEXT_SUMMARY_CHARS = 500;
-const CONTROLLER_INTAKE_TIMEOUT_CAP_MS = 180_000;
 const CONTROLLER_INTAKE_SESSION_PREFIX = "teamclaw-controller-web:";
+const CONTROLLER_INTAKE_AGENT_SESSION_RE = /^agent:[^:]+:(teamclaw-controller-web:[a-zA-Z0-9:_-]{1,120})$/;
+const CONTROLLER_RUN_WAIT_SLICE_MS = 30_000;
+const CONTROLLER_RATE_LIMIT_STALL_PROBE_MS = 5 * 60 * 1000;
+const CONTROLLER_RATE_LIMIT_PROBE_TIMEOUT_MS = 60_000;
+const CONTROLLER_RATE_LIMIT_WAITING_SENTINEL = "TEAMCLAW_STILL_WAITING";
+const controllerIntakeQueue = new Map<string, Promise<void>>();
+
+export function buildControllerIntakeSystemPrompt(
+  deps: Pick<ControllerHttpDeps, "config" | "getTeamState">,
+): string {
+  const injector = createControllerPromptInjector({
+    config: deps.config,
+    getTeamState: deps.getTeamState,
+  });
+  return injector()?.prependSystemContext ?? "";
+}
 
 function mapTaskStatusToExecutionStatus(taskStatus: TaskStatus, current?: TaskExecution["status"]): TaskExecution["status"] {
   switch (taskStatus) {
@@ -101,6 +130,33 @@ function ensureTaskExecution(task: TaskInfo): TaskExecution {
   return task.execution;
 }
 
+function resetTaskForFreshAttempt(task: TaskInfo): void {
+  delete task.startedAt;
+  delete task.completedAt;
+  delete task.result;
+  delete task.error;
+  delete task.resultContract;
+  if (task.execution) {
+    task.execution.status = "pending";
+    delete task.execution.runId;
+    delete task.execution.sessionKey;
+    delete task.execution.startedAt;
+    delete task.execution.endedAt;
+    task.execution.lastUpdatedAt = Date.now();
+  }
+}
+
+function buildTaskExecutionIdentity(taskId: string, workerId: string): {
+  executionSessionKey: string;
+  executionIdempotencyKey: string;
+} {
+  const attemptId = generateId();
+  return {
+    executionSessionKey: `teamclaw-task-${taskId}-${attemptId}`,
+    executionIdempotencyKey: `teamclaw-${taskId}-${workerId}-${attemptId}`,
+  };
+}
+
 function appendTaskExecutionEvent(task: TaskInfo, input: TaskExecutionEventInput): TaskExecutionEvent {
   const now = input.createdAt ?? Date.now();
   const execution = ensureTaskExecution(task);
@@ -417,6 +473,29 @@ function extractLastAssistantText(messages: unknown[]): string {
   return JSON.stringify(lastAssistant);
 }
 
+function formatDuration(timeoutMs: number): string {
+  const totalSeconds = Math.ceil(timeoutMs / 1000);
+  if (totalSeconds % 3600 === 0) {
+    const hours = totalSeconds / 3600;
+    return `${hours} hour${hours === 1 ? "" : "s"}`;
+  }
+  if (totalSeconds % 60 === 0) {
+    const minutes = totalSeconds / 60;
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  }
+  return `${totalSeconds} second${totalSeconds === 1 ? "" : "s"}`;
+}
+
+function isRateLimitMessage(value: string): boolean {
+  return /(rate[_ ]limit|too many requests|429\b|resource has been exhausted|tokens per day|quota|throttl)/i.test(
+    String(value || ""),
+  );
+}
+
+function isStillWaitingResponse(value: string): boolean {
+  return value.replace(/\s+/g, " ").trim() === CONTROLLER_RATE_LIMIT_WAITING_SENTINEL;
+}
+
 function normalizeControllerIntakeSessionKey(input: unknown): string {
   const fallback = `${CONTROLLER_INTAKE_SESSION_PREFIX}default`;
   if (typeof input !== "string") {
@@ -424,40 +503,400 @@ function normalizeControllerIntakeSessionKey(input: unknown): string {
   }
 
   const trimmed = input.trim();
-  if (!trimmed || !/^[a-zA-Z0-9:_-]{1,120}$/.test(trimmed)) {
+  if (!trimmed) {
+    return fallback;
+  }
+
+  const runtimeMatch = trimmed.match(CONTROLLER_INTAKE_AGENT_SESSION_RE);
+  if (trimmed.startsWith("agent:") && !runtimeMatch) {
     return fallback;
   }
 
-  return trimmed.startsWith(CONTROLLER_INTAKE_SESSION_PREFIX)
-    ? trimmed
-    : `${CONTROLLER_INTAKE_SESSION_PREFIX}${trimmed}`;
+  const logicalKey = runtimeMatch?.[1] ?? trimmed;
+  if (!/^[a-zA-Z0-9:_-]{1,120}$/.test(logicalKey)) {
+    return fallback;
+  }
+
+  return logicalKey.startsWith(CONTROLLER_INTAKE_SESSION_PREFIX)
+    ? logicalKey
+    : `${CONTROLLER_INTAKE_SESSION_PREFIX}${logicalKey}`;
+}
+
+async function withSerializedControllerIntake<T>(
+  sessionKey: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const normalizedSessionKey = normalizeControllerIntakeSessionKey(sessionKey);
+  const previous = controllerIntakeQueue.get(normalizedSessionKey) ?? Promise.resolve();
+  let releaseCurrent!: () => void;
+  const current = new Promise<void>((resolve) => {
+    releaseCurrent = resolve;
+  });
+  controllerIntakeQueue.set(normalizedSessionKey, current);
+  try {
+    await previous;
+    return await fn();
+  } finally {
+    releaseCurrent();
+    if (controllerIntakeQueue.get(normalizedSessionKey) === current) {
+      controllerIntakeQueue.delete(normalizedSessionKey);
+    }
+  }
 }
 
 function collectTaskIds(state: TeamState | null): Set<string> {
   return new Set(Object.keys(state?.tasks ?? {}));
 }
 
+function normalizeControllerTaskMatchText(input: unknown): string {
+  return typeof input === "string" ? input.replace(/\s+/g, " ").trim().toLowerCase() : "";
+}
+
+function taskMatchesManifestCreatedTask(
+  task: TaskInfo,
+  manifestTask: ControllerOrchestrationManifest["createdTasks"][number],
+): boolean {
+  if (normalizeControllerTaskMatchText(task.title) !== normalizeControllerTaskMatchText(manifestTask.title)) {
+    return false;
+  }
+  if (manifestTask.assignedRole && task.assignedRole && manifestTask.assignedRole !== task.assignedRole) {
+    return false;
+  }
+  if (manifestTask.assignedRole && !task.assignedRole) {
+    return false;
+  }
+  return task.createdBy === "controller";
+}
+
+function scoreControllerTaskBindingCandidate(task: TaskInfo): number {
+  switch (task.status) {
+    case "pending":
+      return 6;
+    case "assigned":
+      return 5;
+    case "in_progress":
+      return 4;
+    case "review":
+      return 3;
+    case "blocked":
+      return 2;
+    case "completed":
+      return 1;
+    case "failed":
+    default:
+      return 0;
+  }
+}
+
+function reconcileControllerManifestTaskBindings(
+  sessionKey: string,
+  createdTaskIds: string[],
+  manifest: ControllerOrchestrationManifest | undefined,
+  deps: ControllerHttpDeps,
+): { taskIds: string[]; linkedTaskIds: string[] } {
+  if (!manifest || manifest.createdTasks.length === 0) {
+    return { taskIds: createdTaskIds, linkedTaskIds: [] };
+  }
+
+  const normalizedSessionKey = normalizeControllerIntakeSessionKey(sessionKey);
+  const linkedTaskIds: string[] = [];
+
+  deps.updateTeamState((state) => {
+    const usedTaskIds = new Set(createdTaskIds);
+    for (const manifestTask of manifest.createdTasks) {
+      const existingTaskId = Array.from(usedTaskIds).find((taskId) => {
+        const task = state.tasks[taskId];
+        return !!task && taskMatchesManifestCreatedTask(task, manifestTask);
+      });
+      const matchedTask = existingTaskId
+        ? state.tasks[existingTaskId]
+        : Object.values(state.tasks)
+          .filter((task) => !usedTaskIds.has(task.id))
+          .filter((task) => taskMatchesManifestCreatedTask(task, manifestTask))
+          .sort((left, right) => {
+            const scoreDelta = scoreControllerTaskBindingCandidate(right) - scoreControllerTaskBindingCandidate(left);
+            if (scoreDelta !== 0) {
+              return scoreDelta;
+            }
+            return right.updatedAt - left.updatedAt;
+          })[0];
+
+      if (!matchedTask) {
+        continue;
+      }
+
+      if (matchedTask.controllerSessionKey !== normalizedSessionKey) {
+        matchedTask.controllerSessionKey = normalizedSessionKey;
+      }
+      if (!usedTaskIds.has(matchedTask.id)) {
+        usedTaskIds.add(matchedTask.id);
+        linkedTaskIds.push(matchedTask.id);
+      }
+    }
+  });
+
+  return {
+    taskIds: Array.from(new Set([...createdTaskIds, ...linkedTaskIds])),
+    linkedTaskIds,
+  };
+}
+
 function tagControllerCreatedTasks(
   taskIdsBeforeRun: Set<string>,
   sessionKey: string,
   deps: ControllerHttpDeps,
 ): string[] {
+  const normalizedSessionKey = normalizeControllerIntakeSessionKey(sessionKey);
   const taggedTaskIds: string[] = [];
   deps.updateTeamState((state) => {
     for (const task of Object.values(state.tasks)) {
       if (taskIdsBeforeRun.has(task.id)) {
         continue;
       }
-      if (task.createdBy !== "controller" || task.controllerSessionKey) {
+      if (task.createdBy !== "controller") {
+        continue;
+      }
+      if (!task.controllerSessionKey) {
+        task.controllerSessionKey = normalizedSessionKey;
+      }
+      if (normalizeControllerIntakeSessionKey(task.controllerSessionKey) !== normalizedSessionKey) {
         continue;
       }
-      task.controllerSessionKey = sessionKey;
       taggedTaskIds.push(task.id);
     }
   });
   return taggedTaskIds;
 }
 
+function isActiveControllerRun(run: ControllerRunInfo): boolean {
+  return run.status === "pending" || run.status === "running";
+}
+
+function findLatestControllerRunIdForSession(
+  sessionKey: string,
+  state: TeamState | null,
+  options?: { preferActive?: boolean },
+): string | null {
+  const normalizedSessionKey = normalizeControllerIntakeSessionKey(sessionKey);
+  const matchingRuns = Object.values(state?.controllerRuns ?? {})
+    .filter((run) => normalizeControllerIntakeSessionKey(run.sessionKey) === normalizedSessionKey)
+    .sort((left, right) => {
+      if (options?.preferActive) {
+        const leftScore = isActiveControllerRun(left) ? 1 : 0;
+        const rightScore = isActiveControllerRun(right) ? 1 : 0;
+        if (leftScore !== rightScore) {
+          return rightScore - leftScore;
+        }
+      }
+      return right.updatedAt - left.updatedAt;
+    });
+  return matchingRuns[0]?.id ?? null;
+}
+
+function resolveControllerWorkflowSessionKey(task: TaskInfo, state: TeamState | null): string | undefined {
+  if (task.controllerSessionKey) {
+    return normalizeControllerIntakeSessionKey(task.controllerSessionKey);
+  }
+  if (!state || task.createdBy !== "controller") {
+    return undefined;
+  }
+
+  const sortedRuns = Object.values(state.controllerRuns)
+    .sort((left, right) => right.updatedAt - left.updatedAt);
+
+  const directRun = sortedRuns.find((run) =>
+    run.sourceTaskId === task.id || run.createdTaskIds.includes(task.id),
+  );
+  if (directRun) {
+    return normalizeControllerIntakeSessionKey(directRun.sessionKey);
+  }
+
+  const manifestRun = sortedRuns.find((run) =>
+    run.manifest?.createdTasks.some((manifestTask) => taskMatchesManifestCreatedTask(task, manifestTask)),
+  );
+  return manifestRun ? normalizeControllerIntakeSessionKey(manifestRun.sessionKey) : undefined;
+}
+
+function buildControllerManifestEventMessage(manifest: ControllerOrchestrationManifest): string {
+  const parts = [
+    `Structured orchestration manifest recorded.`,
+    `roles=${manifest.requiredRoles.join(", ") || "none"}`,
+    `created=${manifest.createdTasks.length}`,
+    `deferred=${manifest.deferredTasks.length}`,
+  ];
+  if (manifest.clarificationsNeeded) {
+    parts.push(`clarifications=${manifest.clarificationQuestions.length}`);
+  }
+  return parts.join(" ");
+}
+
+function buildControllerManifestReply(
+  manifest: ControllerOrchestrationManifest | undefined,
+  createdTaskIds: string[],
+  state: TeamState | null,
+  fallbackReply: string,
+): string {
+  if (!manifest) {
+    const warning = "Warning: controller did not submit a structured orchestration manifest for this run.";
+    return fallbackReply ? `${fallbackReply}\n\n${warning}` : warning;
+  }
+
+  const actualCreatedTasks = createdTaskIds
+    .map((taskId) => state?.tasks?.[taskId])
+    .filter((task): task is TaskInfo => !!task);
+
+  const lines: string[] = [
+    `Requirement summary: ${manifest.requirementSummary}`,
+    `Required roles: ${manifest.requiredRoles.join(", ") || "none"}`,
+  ];
+
+  if (actualCreatedTasks.length > 0) {
+    lines.push("", "Created execution-ready tasks:");
+    for (const task of actualCreatedTasks) {
+      const roleLabel = task.assignedRole ? ` (${task.assignedRole})` : "";
+      lines.push(`- [${task.id}] ${task.title}${roleLabel}`);
+    }
+  } else if (manifest.createdTasks.length > 0) {
+    lines.push("", "Manifest planned created tasks:");
+    for (const task of manifest.createdTasks) {
+      const roleLabel = task.assignedRole ? ` (${task.assignedRole})` : "";
+      lines.push(`- ${task.title}${roleLabel}: ${task.expectedOutcome}`);
+    }
+  } else {
+    lines.push("", "Created execution-ready tasks: none.");
+  }
+
+  if (manifest.deferredTasks.length > 0) {
+    lines.push("", "Deferred tasks:");
+    for (const task of manifest.deferredTasks) {
+      const roleLabel = task.assignedRole ? ` (${task.assignedRole})` : "";
+      lines.push(`- ${task.title}${roleLabel}: blocked by ${task.blockedBy}; create when ${task.whenReady}`);
+    }
+  }
+
+  if (manifest.clarificationsNeeded) {
+    lines.push("", "Clarifications needed:");
+    for (const question of manifest.clarificationQuestions) {
+      lines.push(`- ${question}`);
+    }
+  }
+
+  if (manifest.handoffPlan) {
+    lines.push("", `Handoff plan: ${manifest.handoffPlan}`);
+  }
+  if (manifest.notes) {
+    lines.push("", `Notes: ${manifest.notes}`);
+  }
+  if (manifest.createdTasks.length !== createdTaskIds.length) {
+    lines.push(
+      "",
+      `Warning: manifest declared ${manifest.createdTasks.length} created task(s), but TeamClaw recorded ${createdTaskIds.length}.`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function summarizeManifestExpectedOutcome(task: TaskInfo): string {
+  const raw = task.result || task.progress || task.description || "";
+  const normalized = raw.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    return "Produce the concrete deliverable described by this task and report the result back to the controller.";
+  }
+  if (normalized.length <= 180) {
+    return normalized;
+  }
+  return `${normalized.slice(0, 180).trimEnd()}…`;
+}
+
+function inferManifestRolesFromText(text: string): RoleId[] {
+  const normalized = text.toLowerCase();
+  const roleIds: RoleId[] = [];
+  for (const role of ROLES) {
+    if (normalized.includes(role.id) || normalized.includes(role.label.toLowerCase())) {
+      roleIds.push(role.id);
+    }
+  }
+  return roleIds;
+}
+
+function inferClarificationQuestionsFromReply(text: string): string[] {
+  const candidates = text
+    .split(/\n+/)
+    .map((line) => line.trim())
+    .filter((line) => line.includes("?"))
+    .map((line) => line.replace(/^[-*]\s*/, ""))
+    .filter(Boolean);
+  return Array.from(new Set(candidates)).slice(0, 5);
+}
+
+function buildBackfilledControllerManifest(
+  request: string,
+  rawReply: string,
+  createdTaskIds: string[],
+  state: TeamState | null,
+): ControllerOrchestrationManifest {
+  const actualCreatedTasks = createdTaskIds
+    .map((taskId) => state?.tasks?.[taskId])
+    .filter((task): task is TaskInfo => !!task);
+  const inferredRoles = new Set<RoleId>();
+  for (const task of actualCreatedTasks) {
+    if (task.assignedRole) {
+      inferredRoles.add(task.assignedRole);
+    }
+  }
+  for (const roleId of inferManifestRolesFromText(rawReply)) {
+    inferredRoles.add(roleId);
+  }
+  const clarificationQuestions = inferClarificationQuestionsFromReply(rawReply);
+  return {
+    version: "1.0",
+    requirementSummary: request.replace(/\s+/g, " ").trim() || "Controller requirement summary unavailable.",
+    requiredRoles: Array.from(inferredRoles),
+    clarificationsNeeded: clarificationQuestions.length > 0 && actualCreatedTasks.length === 0,
+    clarificationQuestions,
+    createdTasks: actualCreatedTasks.map((task) => ({
+      title: task.title,
+      assignedRole: task.assignedRole,
+      expectedOutcome: summarizeManifestExpectedOutcome(task),
+    })),
+    deferredTasks: [],
+    handoffPlan: actualCreatedTasks.length > 0
+      ? "Assigned workers should complete the created execution-ready tasks, report progress, and let the controller schedule downstream work after prerequisites are satisfied."
+      : undefined,
+    notes: "Backfilled by the controller because the model did not submit the required structured manifest.",
+  };
+}
+
+function ensureControllerManifest(
+  controllerRunId: string,
+  sessionKey: string,
+  request: string,
+  rawReply: string,
+  createdTaskIds: string[],
+  deps: ControllerHttpDeps,
+): ControllerOrchestrationManifest {
+  const currentState = deps.getTeamState();
+  const existingManifest = currentState?.controllerRuns?.[controllerRunId]?.manifest;
+  if (existingManifest) {
+    return existingManifest;
+  }
+
+  const manifest = buildBackfilledControllerManifest(request, rawReply, createdTaskIds, currentState);
+  updateControllerRun(controllerRunId, deps, (run) => {
+    run.manifest = manifest;
+    appendControllerRunEvent(run, {
+      type: "warning",
+      phase: "manifest_backfilled",
+      source: "controller",
+      status: "running",
+      sessionKey,
+      message: "Controller did not submit a structured manifest; TeamClaw backfilled a minimal manifest from the recorded run state.",
+    });
+  });
+  return manifest;
+}
+
 function buildControllerFollowUpMessage(task: TaskInfo): string {
   const parts = [
     `A controller-created TeamClaw task has ${task.status === "failed" ? "failed" : "completed"}.`,
@@ -472,6 +911,10 @@ function buildControllerFollowUpMessage(task: TaskInfo): string {
   if (task.result) {
     parts.push("", "## Task Result", task.result);
   }
+  const resultContractSection = buildResultContractSection(task);
+  if (resultContractSection) {
+    parts.push("", resultContractSection);
+  }
   if (task.error) {
     parts.push("", "## Task Error", task.error);
   }
@@ -489,11 +932,40 @@ function buildControllerFollowUpMessage(task: TaskInfo): string {
   return parts.filter(Boolean).join("\n");
 }
 
+function buildControllerRateLimitProbeMessage(
+  sourceTaskId?: string,
+  sourceTaskTitle?: string,
+): string {
+  const workflowLabel = sourceTaskTitle
+    ? `${sourceTaskTitle}${sourceTaskId ? ` (${sourceTaskId})` : ""}`
+    : (sourceTaskId ? `task ${sourceTaskId}` : "this controller workflow");
+  return [
+    `This is a follow-up check for ${workflowLabel}.`,
+    "The earlier controller run appears to be delayed by upstream model rate limiting.",
+    "Do not restart the workflow from scratch.",
+    "Do not duplicate tasks that already exist, are active, or are completed.",
+    "If the earlier controller follow-up is fully complete now, immediately submit the required structured manifest for that same workflow step and provide the final orchestration reply.",
+    `If the earlier controller follow-up is not complete yet, reply with exactly ${CONTROLLER_RATE_LIMIT_WAITING_SENTINEL}.`,
+  ].join("\n");
+}
+
 async function continueControllerWorkflow(task: TaskInfo, deps: ControllerHttpDeps): Promise<void> {
-  if (task.createdBy !== "controller" || !task.controllerSessionKey) {
+  if (task.createdBy !== "controller") {
     return;
   }
-  await runControllerIntake(buildControllerFollowUpMessage(task), task.controllerSessionKey, deps, {
+  const sessionKey = resolveControllerWorkflowSessionKey(task, deps.getTeamState());
+  if (!sessionKey) {
+    return;
+  }
+  if (task.controllerSessionKey !== sessionKey) {
+    deps.updateTeamState((state) => {
+      const currentTask = state.tasks[task.id];
+      if (currentTask) {
+        currentTask.controllerSessionKey = sessionKey;
+      }
+    });
+  }
+  await runControllerIntake(buildControllerFollowUpMessage(task), sessionKey, deps, {
     source: "task_follow_up",
     sourceTaskId: task.id,
     sourceTaskTitle: task.title,
@@ -509,6 +981,22 @@ async function runControllerIntake(
     sourceTaskId?: string;
     sourceTaskTitle?: string;
   },
+): Promise<{ sessionKey: string; runId: string; reply: string; controllerRunId: string }> {
+  const normalizedSessionKey = normalizeControllerIntakeSessionKey(sessionKey);
+  return withSerializedControllerIntake(normalizedSessionKey, () =>
+    runControllerIntakeUnlocked(message, normalizedSessionKey, deps, options),
+  );
+}
+
+async function runControllerIntakeUnlocked(
+  message: string,
+  sessionKey: string,
+  deps: ControllerHttpDeps,
+  options?: {
+    source?: ControllerRunSource;
+    sourceTaskId?: string;
+    sourceTaskTitle?: string;
+  },
 ): Promise<{ sessionKey: string; runId: string; reply: string; controllerRunId: string }> {
   const taskIdsBeforeRun = collectTaskIds(deps.getTeamState());
   const controllerRun = createControllerRun(message, sessionKey, deps, options);
@@ -524,6 +1012,7 @@ async function runControllerIntake(
   const runResult = await deps.runtime.subagent.run({
     sessionKey,
     message,
+    extraSystemPrompt: buildControllerIntakeSystemPrompt(deps),
     idempotencyKey: `controller-intake-${generateId()}`,
   });
   recordControllerRunEvent(controllerRun.id, {
@@ -536,10 +1025,133 @@ async function runControllerIntake(
     message: `Controller intake started (${runResult.runId}).`,
   }, deps);
 
-  const waitResult = await deps.runtime.subagent.waitForRun({
-    runId: runResult.runId,
-    timeoutMs: Math.min(deps.config.taskTimeoutMs, CONTROLLER_INTAKE_TIMEOUT_CAP_MS),
-  });
+  const rateLimitState: {
+    active: boolean;
+    visibleAt?: number;
+    nextProbeAt?: number;
+    probeCount: number;
+  } = {
+    active: false,
+    probeCount: 0,
+  };
+
+  const markRateLimitWaiting = async (): Promise<void> => {
+    if (rateLimitState.active) {
+      return;
+    }
+    const now = Date.now();
+    rateLimitState.active = true;
+    rateLimitState.visibleAt = now;
+    rateLimitState.nextProbeAt = now + CONTROLLER_RATE_LIMIT_STALL_PROBE_MS;
+    recordControllerRunEvent(controllerRun.id, {
+      type: "progress",
+      phase: "model_rate_limit_waiting",
+      source: "controller",
+      status: "running",
+      sessionKey,
+      runId: runResult.runId,
+      message: "Model rate limit reached. OpenClaw is retrying upstream; TeamClaw will keep waiting for the controller workflow to continue.",
+    }, deps);
+  };
+
+  const clearRateLimitWaiting = (): void => {
+    rateLimitState.active = false;
+    rateLimitState.visibleAt = undefined;
+    rateLimitState.nextProbeAt = undefined;
+  };
+
+  const extractSessionAssistantReply = async (): Promise<string> => {
+    const sessionMessages = await deps.runtime.subagent.getSessionMessages({
+      sessionKey,
+      limit: 100,
+    });
+    return extractLastAssistantText(sessionMessages.messages);
+  };
+
+  const probeRateLimitedControllerCompletion = async (): Promise<string | null> => {
+    rateLimitState.probeCount += 1;
+    const now = Date.now();
+    rateLimitState.visibleAt = now;
+    rateLimitState.nextProbeAt = now + CONTROLLER_RATE_LIMIT_STALL_PROBE_MS;
+    recordControllerRunEvent(controllerRun.id, {
+      type: "progress",
+      phase: "model_rate_limit_probe",
+      source: "controller",
+      status: "running",
+      sessionKey,
+      runId: runResult.runId,
+      message: `Model rate limit has delayed controller orchestration for over ${formatDuration(CONTROLLER_RATE_LIMIT_STALL_PROBE_MS)}. Re-checking whether this workflow step has already completed.`,
+    }, deps);
+
+    const probeRun = await deps.runtime.subagent.run({
+      sessionKey,
+      message: buildControllerRateLimitProbeMessage(options?.sourceTaskId, options?.sourceTaskTitle),
+      extraSystemPrompt: buildControllerIntakeSystemPrompt(deps),
+      idempotencyKey: `${runResult.runId}:rate-limit-probe:${rateLimitState.probeCount}`,
+    });
+    const probeWait = await deps.runtime.subagent.waitForRun({
+      runId: probeRun.runId,
+      timeoutMs: CONTROLLER_RATE_LIMIT_PROBE_TIMEOUT_MS,
+    });
+
+    if (probeWait.status !== "ok") {
+      return null;
+    }
+
+    const probeReply = await extractSessionAssistantReply();
+    if (!probeReply || isRateLimitMessage(probeReply) || isStillWaitingResponse(probeReply)) {
+      recordControllerRunEvent(controllerRun.id, {
+        type: "progress",
+        phase: "model_rate_limit_still_waiting",
+        source: "controller",
+        status: "running",
+        sessionKey,
+        runId: runResult.runId,
+        message: "The controller workflow is still waiting on model availability. TeamClaw will continue waiting.",
+      }, deps);
+      return null;
+    }
+
+    clearRateLimitWaiting();
+    return probeReply;
+  };
+
+  let waitResult: Awaited<ReturnType<typeof deps.runtime.subagent.waitForRun>> = { status: "timeout" };
+  let completionOverride: string | null = null;
+  const deadline = Date.now() + deps.config.taskTimeoutMs;
+  while (true) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      waitResult = { status: "timeout" };
+      break;
+    }
+
+    if (rateLimitState.active && (rateLimitState.nextProbeAt ?? Number.POSITIVE_INFINITY) <= Date.now()) {
+      completionOverride = await probeRateLimitedControllerCompletion();
+      if (completionOverride) {
+        waitResult = { status: "ok" };
+        break;
+      }
+    }
+
+    const sliceTimeoutMs = Math.max(1_000, Math.min(CONTROLLER_RUN_WAIT_SLICE_MS, remainingMs));
+    waitResult = await deps.runtime.subagent.waitForRun({
+      runId: runResult.runId,
+      timeoutMs: sliceTimeoutMs,
+    });
+
+    if (waitResult.status === "ok") {
+      clearRateLimitWaiting();
+      break;
+    }
+    if (waitResult.status === "error") {
+      if (isRateLimitMessage(waitResult.error || "")) {
+        await markRateLimitWaiting();
+        continue;
+      }
+      break;
+    }
+  }
 
   if (waitResult.status === "timeout") {
     const createdTaskIds = tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
@@ -579,17 +1191,24 @@ async function runControllerIntake(
 
   const createdTaskIds = tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
 
-  const sessionMessages = await deps.runtime.subagent.getSessionMessages({
-    sessionKey,
-    limit: 100,
-  });
-  const reply = extractLastAssistantText(sessionMessages.messages)
+  const rawReply = completionOverride || await extractSessionAssistantReply()
     || "Controller completed the intake run but did not return any text.";
+  const recordedManifest = ensureControllerManifest(
+    controllerRun.id,
+    sessionKey,
+    message,
+    rawReply,
+    createdTaskIds,
+    deps,
+  );
+  const reconciledTasks = reconcileControllerManifestTaskBindings(sessionKey, createdTaskIds, recordedManifest, deps);
+  const latestTeamState = deps.getTeamState();
+  const reply = buildControllerManifestReply(recordedManifest, reconciledTasks.taskIds, latestTeamState, rawReply);
 
   updateControllerRun(controllerRun.id, deps, (run) => {
     run.reply = reply;
     run.error = undefined;
-    run.createdTaskIds = createdTaskIds;
+    run.createdTaskIds = reconciledTasks.taskIds;
     appendControllerRunEvent(run, {
       type: "output",
       phase: "final_reply",
@@ -599,7 +1218,18 @@ async function runControllerIntake(
       runId: runResult.runId,
       message: reply,
     });
-    if (createdTaskIds.length > 0) {
+    if (reconciledTasks.linkedTaskIds.length > 0) {
+      appendControllerRunEvent(run, {
+        type: "lifecycle",
+        phase: "tasks_linked",
+        source: "controller",
+        status: "running",
+        sessionKey,
+        runId: runResult.runId,
+        message: `Controller linked ${reconciledTasks.linkedTaskIds.length} existing task(s) into this workflow: ${reconciledTasks.linkedTaskIds.join(", ")}`,
+      });
+    }
+    if (reconciledTasks.taskIds.length > 0) {
       appendControllerRunEvent(run, {
         type: "lifecycle",
         phase: "tasks_created",
@@ -607,7 +1237,7 @@ async function runControllerIntake(
         status: "running",
         sessionKey,
         runId: runResult.runId,
-        message: `Controller created ${createdTaskIds.length} task(s): ${createdTaskIds.join(", ")}`,
+        message: `Controller activated ${reconciledTasks.taskIds.length} execution-ready task(s): ${reconciledTasks.taskIds.join(", ")}`,
       });
     }
     appendControllerRunEvent(run, {
@@ -631,7 +1261,13 @@ async function runControllerIntake(
 
 function summarizeTaskForAssignment(task: TaskInfo): string {
   const lastExecutionMessage = task.execution?.events[task.execution.events.length - 1]?.message;
-  const raw = task.result || task.progress || lastExecutionMessage || task.description || "";
+  const contractSummary = task.resultContract
+    ? [
+        task.resultContract.summary,
+        ...task.resultContract.deliverables.slice(0, 3).map((deliverable) => `${deliverable.kind}: ${deliverable.value}`),
+      ].join(" | ")
+    : "";
+  const raw = contractSummary || task.result || task.progress || lastExecutionMessage || task.description || "";
   const normalized = raw.replace(/\s+/g, " ").trim();
   if (!normalized) {
     return "No upstream summary available.";
@@ -911,8 +1547,11 @@ function applyTaskResult(
     });
 
     if (task.assignedWorkerId && s.workers[task.assignedWorkerId]) {
-      s.workers[task.assignedWorkerId].status = "idle";
-      s.workers[task.assignedWorkerId].currentTaskId = undefined;
+      const assignedWorker = s.workers[task.assignedWorkerId];
+      if (assignedWorker.status !== "offline") {
+        assignedWorker.status = "idle";
+      }
+      assignedWorker.currentTaskId = undefined;
     }
   });
 
@@ -923,6 +1562,14 @@ function applyTaskResult(
     }
     wsServer.broadcastUpdate({ type: "task:completed", data: serializeTask(updatedTask) });
     logger.info(`Controller: task ${taskId} ${error ? "failed" : "completed"}`);
+    if (error && updatedTask.assignedWorkerId && deps.workerProvisioningManager?.hasManagedWorker(updatedTask.assignedWorkerId)) {
+      void deps.workerProvisioningManager.onWorkerRemoved(
+        updatedTask.assignedWorkerId,
+        `task ${taskId} failed; retiring managed worker before retry`,
+      ).catch((err) => {
+        logger.warn(`Controller: failed to retire managed worker ${updatedTask.assignedWorkerId}: ${String(err)}`);
+      });
+    }
     if (updatedTask.assignedWorkerId) {
       void autoAssignPendingTasks(deps, updatedTask.assignedWorkerId).catch((err) => {
         logger.warn(
@@ -931,7 +1578,7 @@ function applyTaskResult(
       });
     }
     scheduleProvisioningReconcile(deps, `task-result:${taskId}`);
-    if (!error && updatedTask.createdBy === "controller" && updatedTask.controllerSessionKey) {
+    if (!error && updatedTask.createdBy === "controller") {
       void continueControllerWorkflow(updatedTask, deps).catch((err) => {
         logger.warn(
           `Controller: failed to continue intake workflow after ${taskId}: ${String(err)}`,
@@ -943,6 +1590,89 @@ function applyTaskResult(
   return updatedTask;
 }
 
+function ensureTaskResultContract(
+  taskId: string,
+  result: string,
+  error: string | undefined,
+  deps: ControllerHttpDeps,
+): WorkerTaskResultContract | undefined {
+  const state = deps.getTeamState();
+  const currentTask = state?.tasks[taskId];
+  if (!currentTask) {
+    return undefined;
+  }
+  if (currentTask.resultContract) {
+    return currentTask.resultContract;
+  }
+
+  const contract = backfillWorkerTaskResultContract(currentTask, result, error);
+  deps.updateTeamState((teamState) => {
+    const task = teamState.tasks[taskId];
+    if (!task || task.resultContract) {
+      return;
+    }
+    task.resultContract = contract;
+  });
+  recordTaskExecutionEvent(taskId, {
+    type: "lifecycle",
+    phase: "result_contract_backfilled",
+    source: "controller",
+    message: "Worker did not submit a structured result contract; TeamClaw backfilled one from the recorded task result.",
+    workerId: currentTask.assignedWorkerId,
+    role: currentTask.assignedRole,
+  }, deps);
+  return contract;
+}
+
+function buildResultContractSection(task: TaskInfo): string {
+  const contract = task.resultContract;
+  if (!contract) {
+    return "";
+  }
+
+  const lines = [
+    "## Structured Result Contract",
+    `Outcome: ${contract.outcome}`,
+    `Summary: ${contract.summary}`,
+  ];
+  if (contract.deliverables.length > 0) {
+    lines.push("Deliverables:");
+    for (const deliverable of contract.deliverables) {
+      const summary = deliverable.summary ? ` — ${deliverable.summary}` : "";
+      lines.push(`- ${deliverable.kind}: ${deliverable.value}${summary}`);
+    }
+  }
+  if (contract.keyPoints.length > 0) {
+    lines.push("Key points:");
+    for (const keyPoint of contract.keyPoints) {
+      lines.push(`- ${keyPoint}`);
+    }
+  }
+  if (contract.blockers.length > 0) {
+    lines.push("Blockers:");
+    for (const blocker of contract.blockers) {
+      lines.push(`- ${blocker}`);
+    }
+  }
+  if (contract.followUps.length > 0) {
+    lines.push("Suggested follow-ups:");
+    for (const followUp of contract.followUps) {
+      const roleLabel = followUp.targetRole ? ` (${followUp.targetRole})` : "";
+      lines.push(`- ${followUp.type}${roleLabel}: ${followUp.reason}`);
+    }
+  }
+  if (contract.questions.length > 0) {
+    lines.push("Open questions:");
+    for (const question of contract.questions) {
+      lines.push(`- ${question}`);
+    }
+  }
+  if (contract.notes) {
+    lines.push(`Notes: ${contract.notes}`);
+  }
+  return lines.join("\n");
+}
+
 function revertTaskAssignment(taskId: string, workerId: string, deps: ControllerHttpDeps): TaskInfo | undefined {
   const { updateTeamState, wsServer } = deps;
   let revertEvent: TaskExecutionEvent | undefined;
@@ -967,7 +1697,9 @@ function revertTaskAssignment(taskId: string, workerId: string, deps: Controller
 
     const worker = s.workers[workerId];
     if (worker?.currentTaskId === taskId) {
-      worker.status = "idle";
+      if (worker.status !== "offline") {
+        worker.status = "idle";
+      }
       worker.currentTaskId = undefined;
     }
   });
@@ -1054,12 +1786,15 @@ async function dispatchTaskToWorker(
   const repoInfo = buildRepoSyncInfo(repoState, sharedWorkspace);
   const description = buildTaskAssignmentDescription(task, state ?? null, repoInfo);
   const recommendedSkills = resolveRecommendedSkillsForRole(task.assignedRole, task.recommendedSkills ?? []);
+  const executionIdentity = buildTaskExecutionIdentity(task.id, worker.id);
   const assignment: TaskAssignmentPayload = {
     taskId: task.id,
     title: task.title,
     description,
     priority: task.priority,
     recommendedSkills,
+    executionSessionKey: executionIdentity.executionSessionKey,
+    executionIdempotencyKey: executionIdentity.executionIdempotencyKey,
     repo: repoInfo,
   };
 
@@ -1115,6 +1850,7 @@ async function assignTaskToWorker(
     if (options?.assignedRole) {
       task.assignedRole = options.assignedRole;
     }
+    resetTaskForFreshAttempt(task);
     task.updatedAt = Date.now();
 
     targetWorker.status = "busy";
@@ -1241,6 +1977,13 @@ async function handleRequest(
   const requestUrl = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
 
   // ==================== Web UI ====================
+  if (req.method === "GET" && pathname === "/") {
+    res.statusCode = 302;
+    res.setHeader("Location", "/ui");
+    res.end();
+    return;
+  }
+
   if (req.method === "GET" && (pathname === "/ui" || pathname === "/ui/")) {
     const uiPath = path.join(import.meta.dirname, "..", "ui");
     serveStaticFile(res, path.join(uiPath, "index.html"), "text/html; charset=utf-8");
@@ -1386,6 +2129,7 @@ async function handleRequest(
         ) {
           task.status = "pending";
           task.assignedWorkerId = undefined;
+          resetTaskForFreshAttempt(task);
           task.updatedAt = Date.now();
           affectedTaskIds.push(task.id);
         }
@@ -1448,6 +2192,9 @@ async function handleRequest(
     const priority = typeof body.priority === "string" ? body.priority as TaskPriority : "medium";
     const assignedRole = typeof body.assignedRole === "string" ? body.assignedRole as RoleId : undefined;
     const createdBy = typeof body.createdBy === "string" ? body.createdBy : "boss";
+    const controllerSessionKey = createdBy === "controller" && typeof body.controllerSessionKey === "string" && body.controllerSessionKey.trim()
+      ? normalizeControllerIntakeSessionKey(body.controllerSessionKey)
+      : undefined;
     const recommendedSkills = normalizeRecommendedSkills(
       Array.isArray(body.recommendedSkills) ? body.recommendedSkills.map((entry) => String(entry ?? "")) : [],
     );
@@ -1456,6 +2203,10 @@ async function handleRequest(
       sendError(res, 400, "title is required");
       return;
     }
+    if (createdBy === "controller" && shouldBlockControllerWithoutWorkers(deps.config, getTeamState())) {
+      sendError(res, 409, buildControllerNoWorkersMessage());
+      return;
+    }
 
     const taskId = generateId();
     const now = Date.now();
@@ -1470,6 +2221,7 @@ async function handleRequest(
       assignedRole,
       createdBy,
       recommendedSkills: recommendedSkills.length > 0 ? recommendedSkills : undefined,
+      controllerSessionKey,
       createdAt: now,
       updatedAt: now,
     };
@@ -1572,12 +2324,14 @@ async function handleRequest(
     const body = await parseJsonBody(req);
     let statusEvent: TaskExecutionEvent | undefined;
     let progressEvent: TaskExecutionEvent | undefined;
+    let progressContract: WorkerProgressContract | undefined;
 
     const state = updateTeamState((s) => {
       const task = s.tasks[taskId];
       if (!task) return;
       const previousStatus = task.status;
       const previousProgress = task.progress;
+      const previousProgressContract = task.progressContract;
       if (typeof body.status === "string") task.status = body.status as TaskStatus;
       if (typeof body.progress === "string") task.progress = body.progress as string;
       if (typeof body.priority === "string") task.priority = body.priority as TaskPriority;
@@ -1588,6 +2342,12 @@ async function handleRequest(
         );
         task.recommendedSkills = recommendedSkills.length > 0 ? recommendedSkills : undefined;
       }
+      progressContract = normalizeWorkerProgressContract(body.progressContract)
+        ?? (typeof body.progress === "string" ? backfillWorkerProgressContract(body.progress, typeof body.status === "string" ? body.status : undefined) : undefined);
+      if (progressContract) {
+        task.progressContract = progressContract;
+        task.progress = task.progress || progressContract.summary;
+      }
       task.updatedAt = Date.now();
 
       if (typeof body.status === "string" && body.status !== previousStatus) {
@@ -1607,6 +2367,14 @@ async function handleRequest(
           status: task.status === "in_progress" || task.status === "review" ? "running" : undefined,
           message: body.progress as string,
         });
+      } else if (progressContract && JSON.stringify(progressContract) !== JSON.stringify(previousProgressContract)) {
+        progressEvent = appendTaskExecutionEvent(task, {
+          type: "progress",
+          phase: "progress_contract_reported",
+          source: "worker",
+          status: task.status === "in_progress" || task.status === "review" ? "running" : undefined,
+          message: progressContract.summary,
+        });
       }
     });
 
@@ -1665,6 +2433,13 @@ async function handleRequest(
     const taskId = pathname.split("/")[4]!;
     const body = await parseJsonBody(req);
     const targetRole = typeof body.targetRole === "string" ? body.targetRole as RoleId : undefined;
+    const handoffContract = normalizeTaskHandoffContract(body.contract, {
+      targetRole,
+      reason: typeof body.reason === "string" ? body.reason : targetRole ? `The next step should move to ${targetRole}.` : "The task needs a new assignee.",
+      summary: typeof body.summary === "string" ? body.summary : undefined,
+      expectedNextStep: typeof body.expectedNextStep === "string" ? body.expectedNextStep : undefined,
+      artifacts: [],
+    });
 
     const state = getTeamState();
     if (!state?.tasks[taskId]) {
@@ -1673,27 +2448,51 @@ async function handleRequest(
     }
 
     const previousWorkerId = state.tasks[taskId].assignedWorkerId;
+    const avoidPreviousManagedWorker = Boolean(
+      previousWorkerId && deps.workerProvisioningManager?.hasManagedWorker(previousWorkerId),
+    );
 
     updateTeamState((s) => {
-      s.tasks[taskId].status = "pending";
-      s.tasks[taskId].assignedWorkerId = undefined;
-      s.tasks[taskId].assignedRole = targetRole ?? s.tasks[taskId].assignedRole;
-      s.tasks[taskId].updatedAt = Date.now();
+      const task = s.tasks[taskId];
+      task.status = "pending";
+      task.assignedWorkerId = undefined;
+      task.assignedRole = targetRole ?? task.assignedRole;
+      task.lastHandoff = handoffContract;
+      resetTaskForFreshAttempt(task);
+      task.updatedAt = Date.now();
 
       // Free old worker
       if (previousWorkerId && s.workers[previousWorkerId]) {
-        s.workers[previousWorkerId].status = "idle";
-        s.workers[previousWorkerId].currentTaskId = undefined;
+        const previousWorker = s.workers[previousWorkerId];
+        if (previousWorker.status !== "offline") {
+          previousWorker.status = "idle";
+        }
+        previousWorker.currentTaskId = undefined;
       }
     });
 
     await cancelTaskExecution(taskId, previousWorkerId, "handoff", deps);
+    if (avoidPreviousManagedWorker && previousWorkerId) {
+      try {
+        await deps.workerProvisioningManager?.onWorkerRemoved(
+          previousWorkerId,
+          `handoff for ${taskId} requested a fresh managed worker`,
+        );
+      } catch (err) {
+        logger.warn(`Controller: failed to retire previous managed worker ${previousWorkerId}: ${String(err)}`);
+      }
+    }
 
     // Try auto-assign to new role
     const newState = getTeamState()!;
-    const worker = taskRouter.routeTask(newState.tasks[taskId], newState.workers);
+    const routingWorkers = avoidPreviousManagedWorker && previousWorkerId
+      ? Object.fromEntries(Object.entries(newState.workers).filter(([workerId]) => workerId !== previousWorkerId))
+      : newState.workers;
+    const worker = taskRouter.routeTask(newState.tasks[taskId], routingWorkers);
     if (worker) {
       await assignTaskToWorker(taskId, worker, deps, { assignedRole: targetRole });
+    } else {
+      scheduleProvisioningReconcile(deps, `handoff:${taskId}`);
     }
 
     const updatedTask = getTeamState()?.tasks[taskId];
@@ -1702,8 +2501,8 @@ async function handleRequest(
       phase: "handoff",
       source: "controller",
       message: targetRole
-        ? `Task handed off and re-routed to role ${targetRole}.`
-        : "Task handed off for re-routing.",
+        ? `Task handed off and re-routed to role ${targetRole}: ${handoffContract.summary}`
+        : `Task handed off for re-routing: ${handoffContract.summary}`,
       role: targetRole,
     }, deps);
     wsServer.broadcastUpdate({ type: "task:updated", data: serializeTask(updatedTask) });
@@ -1711,6 +2510,48 @@ async function handleRequest(
     return;
   }
 
+  // POST /api/v1/tasks/:id/result-contract
+  if (req.method === "POST" && pathname.match(/^\/api\/v1\/tasks\/[^/]+\/result-contract$/)) {
+    const taskId = pathname.split("/")[4]!;
+    const body = await parseJsonBody(req);
+    const contract = normalizeWorkerTaskResultContract(body.contract ?? body.resultContract);
+    const workerId = typeof body.workerId === "string" ? body.workerId : undefined;
+    const currentTask = getTeamState()?.tasks[taskId];
+    if (!currentTask) {
+      sendError(res, 404, "Task not found");
+      return;
+    }
+    if (!contract) {
+      sendError(res, 400, "result contract is required");
+      return;
+    }
+    if (workerId && !canAcceptWorkerUpdate(currentTask, workerId)) {
+      logger.info(`Controller: ignoring stale result contract for ${taskId} from ${workerId}`);
+      sendJson(res, 202, { status: "ignored", reason: "stale-worker-result-contract" });
+      return;
+    }
+
+    const state = updateTeamState((teamState) => {
+      const task = teamState.tasks[taskId];
+      if (!task) {
+        return;
+      }
+      task.resultContract = contract;
+      task.updatedAt = Date.now();
+    });
+    recordTaskExecutionEvent(taskId, {
+      type: "output",
+      phase: "result_contract_recorded",
+      source: "worker",
+      status: contract.outcome === "failed" ? "failed" : "running",
+      message: contract.summary,
+      workerId,
+      role: currentTask.assignedRole,
+    }, deps);
+    sendJson(res, 201, { task: serializeTask(state.tasks[taskId]) });
+    return;
+  }
+
   // POST /api/v1/tasks/:id/result
   if (req.method === "POST" && pathname.match(/^\/api\/v1\/tasks\/[^/]+\/result$/)) {
     const taskId = pathname.split("/")[4]!;
@@ -1730,11 +2571,32 @@ async function handleRequest(
     }
     const previousWorkerId = getTeamState()?.tasks[taskId]?.assignedWorkerId;
 
+    const submittedContract = normalizeWorkerTaskResultContract(body.contract ?? body.resultContract);
+    if (submittedContract) {
+      updateTeamState((teamState) => {
+        const task = teamState.tasks[taskId];
+        if (!task) {
+          return;
+        }
+        task.resultContract = submittedContract;
+      });
+      recordTaskExecutionEvent(taskId, {
+        type: "output",
+        phase: "result_contract_recorded",
+        source: "worker",
+        status: error ? "failed" : "running",
+        message: submittedContract.summary,
+        workerId,
+        role: currentTask.assignedRole,
+      }, deps);
+    }
+
     const updatedTask = applyTaskResult(taskId, result, error, deps);
+    ensureTaskResultContract(taskId, result, error, deps);
     if (!workerId || workerId !== previousWorkerId) {
       await cancelTaskExecution(taskId, previousWorkerId, "manual result submission", deps);
     }
-    sendJson(res, 200, { task: serializeTask(updatedTask) });
+    sendJson(res, 200, { task: serializeTask(getTeamState()?.tasks[taskId] ?? updatedTask) });
     return;
   }
 
@@ -1792,6 +2654,48 @@ async function handleRequest(
 
   // ==================== Message Routing ====================
 
+  // POST /api/v1/controller/manifest
+  if (req.method === "POST" && pathname === "/api/v1/controller/manifest") {
+    const body = await parseJsonBody(req);
+    const sessionKey = normalizeControllerIntakeSessionKey(body.sessionKey);
+    const manifest = normalizeControllerManifest(body.manifest);
+    if (!manifest) {
+      sendError(res, 400, "manifest is required and must include requirementSummary");
+      return;
+    }
+
+    const runId = findLatestControllerRunIdForSession(sessionKey, deps.getTeamState(), {
+      preferActive: true,
+    });
+    if (!runId) {
+      sendError(res, 404, "Controller run not found for session");
+      return;
+    }
+
+    const updatedRun = updateControllerRun(runId, deps, (run) => {
+      run.manifest = manifest;
+      appendControllerRunEvent(run, {
+        type: "output",
+        phase: "manifest_recorded",
+        source: "controller",
+        status: "running",
+        sessionKey,
+        message: buildControllerManifestEventMessage(manifest),
+      });
+    });
+
+    if (!updatedRun) {
+      sendError(res, 404, "Controller run not found");
+      return;
+    }
+
+    sendJson(res, 201, {
+      controllerRun: serializeControllerRun(updatedRun),
+      manifest,
+    });
+    return;
+  }
+
   // GET /api/v1/controller/runs
   if (req.method === "GET" && pathname === "/api/v1/controller/runs") {
     const state = getTeamState();
@@ -1836,6 +2740,12 @@ async function handleRequest(
       toRole: typeof body.toRole === "string" ? body.toRole as RoleId : undefined,
       type: "direct",
       content: typeof body.content === "string" ? body.content : "",
+      contract: ensureTeamMessageContract(body.contract, {
+        type: "direct",
+        content: typeof body.content === "string" ? body.content : "",
+        toRole: typeof body.toRole === "string" ? body.toRole as RoleId : undefined,
+        taskId: typeof body.taskId === "string" ? body.taskId : undefined,
+      }),
       taskId: typeof body.taskId === "string" ? body.taskId : undefined,
       createdAt: Date.now(),
     };
@@ -1858,6 +2768,11 @@ async function handleRequest(
       fromRole: typeof body.fromRole === "string" ? body.fromRole as RoleId : undefined,
       type: "broadcast",
       content: typeof body.content === "string" ? body.content : "",
+      contract: ensureTeamMessageContract(body.contract, {
+        type: "broadcast",
+        content: typeof body.content === "string" ? body.content : "",
+        taskId: typeof body.taskId === "string" ? body.taskId : undefined,
+      }),
       taskId: typeof body.taskId === "string" ? body.taskId : undefined,
       createdAt: Date.now(),
     };
@@ -1889,6 +2804,14 @@ async function handleRequest(
       toRole: typeof body.toRole === "string" ? body.toRole as RoleId : undefined,
       type: "review-request",
       content: typeof body.content === "string" ? body.content : "",
+      contract: ensureTeamMessageContract(body.contract, {
+        type: "review-request",
+        content: typeof body.content === "string" ? body.content : "",
+        toRole: typeof body.toRole === "string" ? body.toRole as RoleId : undefined,
+        taskId: typeof body.taskId === "string" ? body.taskId : undefined,
+        intent: "review-request",
+        needsResponse: true,
+      }),
       taskId: typeof body.taskId === "string" ? body.taskId : undefined,
       createdAt: Date.now(),
     };
@@ -1994,8 +2917,11 @@ async function handleRequest(
       task.updatedAt = now;
 
       if (assignedWorkerId && s.workers[assignedWorkerId]) {
-        s.workers[assignedWorkerId].status = "idle";
-        s.workers[assignedWorkerId].currentTaskId = undefined;
+        const assignedWorker = s.workers[assignedWorkerId];
+        if (assignedWorker.status !== "offline") {
+          assignedWorker.status = "idle";
+        }
+        assignedWorker.currentTaskId = undefined;
       }
     });
 
@@ -2078,6 +3004,7 @@ async function handleRequest(
       task.status = "pending";
       task.progress = `Clarification answered by ${answeredBy}: ${answer}`;
       task.clarificationRequestId = undefined;
+      resetTaskForFreshAttempt(task);
       task.updatedAt = now;
     });
 
@@ -2092,6 +3019,17 @@ async function handleRequest(
         toRole: clarification.requestedByRole,
         type: "direct",
         content: `Clarification answer for task ${task.id}: ${answer}`,
+        contract: ensureTeamMessageContract(null, {
+          type: "direct",
+          content: `Clarification answer for task ${task.id}: ${answer}`,
+          toRole: clarification.requestedByRole,
+          taskId: task.id,
+          summary: `Clarification answered for task ${task.id}`,
+          details: answer,
+          requestedAction: "Resume the task using this clarification.",
+          needsResponse: false,
+          intent: "update",
+        }),
         taskId: task.id,
         createdAt: now,
       };