@teamclaws/teamclaw 2026.3.26-2 → 2026.4.2-2

package/src/controller/http-server.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import http from "node:http";
+import zlib from "node:zlib";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawPluginApi, PluginLogger } from "../../api.js";
 import type {
@@ -12,6 +13,7 @@ import type {
   PluginConfig,
   RepoSyncInfo,
   RoleId,
+  StartupProvisioningReadiness,
   TaskExecution,
   TaskExecutionEvent,
   TaskExecutionEventInput,
@@ -25,6 +27,7 @@ import type {
   WorkerProgressContract,
   WorkerInfo,
   WorkerTaskResultContract,
+  WorkerTaskResultDeliverable,
 } from "../types.js";
 import {
   parseJsonBody,
@@ -33,16 +36,17 @@ import {
   sendError,
   generateId,
 } from "../protocol.js";
-import { listWorkspaceTree, readWorkspaceFile, readWorkspaceRawFile } from "../workspace-browser.js";
+import { listWorkspaceTree, listWorkspaceSubtree, readWorkspaceFile, readWorkspaceRawFile } from "../workspace-browser.js";
 import { ROLES, normalizeRecommendedSkills, resolveRecommendedSkillsForRole } from "../roles.js";
 import { buildRepoSyncInfo, ensureControllerGitRepo, exportControllerGitBundle, importControllerGitBundle } from "../git-collaboration.js";
-import type { LocalWorkerManager } from "./local-worker-manager.js";
 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 type { PreviewManager } from "./preview-manager.js";
 import { createControllerPromptInjector } from "./prompt-injector.js";
 import { buildControllerNoWorkersMessage, shouldBlockControllerWithoutWorkers } from "./controller-capacity.js";
+import { generateDeliveryReport, isSessionComplete, renderReportHtml, type DeliveryReport } from "./delivery-report.js";
 import {
   backfillWorkerProgressContract,
   backfillWorkerTaskResultContract,
@@ -50,8 +54,20 @@ import {
   normalizeTaskHandoffContract,
   normalizeWorkerProgressContract,
   normalizeWorkerTaskResultContract,
+  enrichDeliverablesWithPreviewInference,
 } from "../interaction-contracts.js";
-import { normalizeControllerManifest } from "./orchestration-manifest.js";
+import {
+  buildTeamClawProjectWorkspacePath,
+  buildTeamClawAgentSessionKey,
+  getTeamClawModelReadiness,
+  resolveTeamClawAgentWorkspaceRootDir,
+  resolveTeamClawWorkspaceDir,
+  resolveTeamClawProjectsDir,
+  deriveProjectSlug,
+} from "../openclaw-workspace.js";
+import { resolvePreferredLanAddress } from "../networking.js";
+import { normalizeClarificationQuestionSchema, normalizeControllerManifest } from "./orchestration-manifest.js";
+import type { KickoffHandler } from "./controller-service.js";
 
 export type ControllerHttpDeps = {
   config: PluginConfig;
@@ -62,8 +78,10 @@ export type ControllerHttpDeps = {
   taskRouter: TaskRouter;
   messageRouter: MessageRouter;
   wsServer: TeamWebSocketServer;
-  localWorkerManager?: LocalWorkerManager;
   workerProvisioningManager?: WorkerProvisioningManager | null;
+  previewManager?: PreviewManager;
+  /** Late-bound kickoff handler for automatic team kickoff on complex projects. */
+  getKickoffHandler?: () => KickoffHandler | undefined;
 };
 
 const MAX_TASK_EXECUTION_EVENTS = 250;
@@ -73,10 +91,44 @@ const MAX_TASK_CONTEXT_SUMMARY_CHARS = 500;
 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 EXISTING_PROJECT_REUSE_HINT_RE = /\b(existing|optimi(?:s|z)e|optimi(?:s|z)ation|improvement|enhanc(?:e|ement)|follow[- ]?up|extend|update|bugfix|bug fix)\b/iu;
+const PROJECT_MATCH_STOPWORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "app",
+  "application",
+  "build",
+  "complete",
+  "existing",
+  "follow",
+  "for",
+  "hub",
+  "improvement",
+  "improvements",
+  "internal",
+  "optimization",
+  "product",
+  "project",
+  "requirement",
+  "request",
+  "studio",
+  "system",
+  "the",
+  "this",
+  "up",
+  "update",
+  "web",
+]);
 const CONTROLLER_RATE_LIMIT_STALL_PROBE_MS = 5 * 60 * 1000;
 const CONTROLLER_RATE_LIMIT_PROBE_TIMEOUT_MS = 60_000;
+const CONTROLLER_INACTIVITY_PROBE_TIMEOUT_MS = 60_000;
 const CONTROLLER_RATE_LIMIT_WAITING_SENTINEL = "TEAMCLAW_STILL_WAITING";
+const CONTROLLER_INTAKE_MAX_RETRIES = 2;
+const CONTROLLER_INTAKE_RETRY_DELAY_MS = 3_000;
+const CONTROLLER_INTAKE_RETRYABLE_ERROR_PATTERN = /(500|502|503|server error|internal error|overloaded|unavailable)/i;
 const controllerIntakeQueue = new Map<string, Promise<void>>();
+const EXTERNAL_WORKER_INSTALL_SPEC = "@teamclaws/teamclaw";
 
 export function buildControllerIntakeSystemPrompt(
   deps: Pick<ControllerHttpDeps, "config" | "getTeamState">,
@@ -88,6 +140,49 @@ export function buildControllerIntakeSystemPrompt(
   return injector()?.prependSystemContext ?? "";
 }
 
+function resolveRequestPort(req: IncomingMessage, fallbackPort: number): number {
+  const hostHeader = req.headers.host?.trim();
+  if (!hostHeader) {
+    return fallbackPort;
+  }
+  try {
+    const parsed = new URL(`http://${hostHeader}`);
+    return parsed.port ? Number(parsed.port) : fallbackPort;
+  } catch {
+    return fallbackPort;
+  }
+}
+
+function resolveRecommendedLanControllerUrl(req: IncomingMessage, fallbackPort: number): string {
+  const port = resolveRequestPort(req, fallbackPort);
+  const preferredLan = resolvePreferredLanAddress();
+  return preferredLan ? `http://${preferredLan}:${port}` : "";
+}
+
+function shellEscapeSingleQuotes(value: string): string {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function buildExternalWorkerInstallInfo(req: IncomingMessage, config: PluginConfig): Record<string, unknown> {
+  const recommendedControllerUrl = resolveRecommendedLanControllerUrl(req, config.port);
+  return {
+    teamName: config.teamName,
+    recommendedControllerUrl,
+    roles: ROLES.map((role) => ({ id: role.id, label: role.label, icon: role.icon })),
+    autoDiscoveryCommandPrefix:
+      `npx -y ${EXTERNAL_WORKER_INSTALL_SPEC} install --yes --install-mode worker --team-name ${shellEscapeSingleQuotes(config.teamName)} --worker-role `,
+    manualCommandPrefix:
+      `npx -y ${EXTERNAL_WORKER_INSTALL_SPEC} install --yes --install-mode worker --team-name ${shellEscapeSingleQuotes(config.teamName)} --worker-role `,
+    manualControllerUrlFlag: recommendedControllerUrl
+      ? ` --controller-url ${shellEscapeSingleQuotes(recommendedControllerUrl)}`
+      : "",
+    manualControllerWarning: recommendedControllerUrl
+      ? "Manual worker installs must use the controller LAN IP, not localhost/127.0.0.1."
+      : "No private LAN IPv4 address was detected on this controller host yet, so manual worker install commands are unavailable until a LAN address exists.",
+    autoDiscoveryWarning: "mDNS auto-discovery only works when the worker and controller are reachable on the same LAN.",
+  };
+}
+
 function mapTaskStatusToExecutionStatus(taskStatus: TaskStatus, current?: TaskExecution["status"]): TaskExecution["status"] {
   switch (taskStatus) {
     case "completed":
@@ -152,7 +247,7 @@ function buildTaskExecutionIdentity(taskId: string, workerId: string): {
 } {
   const attemptId = generateId();
   return {
-    executionSessionKey: `teamclaw-task-${taskId}-${attemptId}`,
+    executionSessionKey: buildTeamClawAgentSessionKey(`teamclaw-task-${taskId}-${attemptId}`),
     executionIdempotencyKey: `teamclaw-${taskId}-${workerId}-${attemptId}`,
   };
 }
@@ -363,10 +458,16 @@ function createControllerRun(
   },
 ): ControllerRunInfo {
   const now = Date.now();
+  const existingState = deps.getTeamState();
+  const inheritedProjectDir = options?.sourceTaskId
+    ? existingState?.tasks[options.sourceTaskId]?.projectDir
+    : resolveProjectDirForSession(sessionKey, existingState)
+      ?? resolveExistingProjectDirFromMessage(message, existingState);
   const run: ControllerRunInfo = {
     id: generateId(),
     title: buildControllerRunTitle(message, options?.source ?? "human", options?.sourceTaskTitle),
     sessionKey,
+    projectDir: inheritedProjectDir ?? deriveProjectSlug(message),
     source: options?.source ?? "human",
     sourceTaskId: options?.sourceTaskId,
     sourceTaskTitle: options?.sourceTaskTitle,
@@ -386,6 +487,154 @@ function createControllerRun(
   return createdRun;
 }
 
+function resolveExistingProjectDirFromMessage(
+  message: string,
+  state: TeamState | null,
+): string | undefined {
+  if (!EXISTING_PROJECT_REUSE_HINT_RE.test(message)) {
+    return undefined;
+  }
+  const normalizedMessage = normalizeProjectMatchingText(message);
+  if (!normalizedMessage) {
+    return undefined;
+  }
+  const explicitAlias = normalizeProjectMatchingText(extractProjectAliasFromText(message) ?? "");
+
+  let best: { projectDir: string; score: number; updatedAt: number } | null = null;
+  const candidates = collectExistingProjectCandidates(state);
+  for (const candidate of candidates) {
+    const normalizedAliases = Array.from(candidate.aliases)
+      .map((alias) => normalizeProjectMatchingText(alias))
+      .filter(Boolean)
+      .reduce<string[]>((acc, alias) => {
+        acc.push(alias);
+        return acc;
+      }, []);
+    const hasExplicitAliasMatch = explicitAlias
+      ? normalizedAliases.some((alias) => alias.includes(explicitAlias) || explicitAlias.includes(alias))
+      : false;
+    if (explicitAlias && !hasExplicitAliasMatch) {
+      continue;
+    }
+    const aliasScore = normalizedAliases
+      .reduce((score, alias) => {
+        if (!alias) {
+          return score;
+        }
+        return normalizedMessage.includes(alias)
+          ? Math.max(score, alias.split(" ").length + 10)
+          : score;
+      }, 0);
+    const tokenScore = scoreProjectTokenOverlap(normalizedMessage, candidate.searchText);
+    const totalScore = Math.max(aliasScore, tokenScore);
+    if (totalScore < 2) {
+      continue;
+    }
+    if (!best || totalScore > best.score || (totalScore === best.score && candidate.updatedAt > best.updatedAt)) {
+      best = {
+        projectDir: candidate.projectDir,
+        score: totalScore,
+        updatedAt: candidate.updatedAt,
+      };
+    }
+  }
+  return best?.projectDir;
+}
+
+function collectExistingProjectCandidates(state: TeamState | null): Array<{
+  projectDir: string;
+  aliases: Set<string>;
+  searchText: string;
+  updatedAt: number;
+}> {
+  const byProjectDir = new Map<string, { aliases: Set<string>; texts: string[]; updatedAt: number }>();
+  const addCandidate = (projectDir: string | undefined, text: string | undefined, updatedAt: number, alias?: string | null) => {
+    if (!projectDir) {
+      return;
+    }
+    const entry = byProjectDir.get(projectDir) ?? { aliases: new Set<string>(), texts: [], updatedAt: 0 };
+    if (text && text.trim()) {
+      entry.texts.push(text);
+    }
+    if (alias && alias.trim()) {
+      entry.aliases.add(alias.trim());
+    }
+    entry.updatedAt = Math.max(entry.updatedAt, updatedAt);
+    byProjectDir.set(projectDir, entry);
+  };
+
+  for (const run of Object.values(state?.controllerRuns ?? {})) {
+    addCandidate(run.projectDir, run.request, run.updatedAt, extractProjectAliasFromText(run.request));
+    addCandidate(run.projectDir, run.title, run.updatedAt, extractProjectAliasFromText(run.title));
+  }
+  for (const task of Object.values(state?.tasks ?? {})) {
+    addCandidate(task.projectDir, task.title, task.updatedAt, extractProjectAliasFromText(task.title));
+    addCandidate(task.projectDir, task.description, task.updatedAt, extractProjectAliasFromText(task.description));
+    addCandidate(task.projectDir, task.resultContract?.summary, task.updatedAt);
+  }
+
+  return Array.from(byProjectDir.entries()).map(([projectDir, entry]) => ({
+    projectDir,
+    aliases: entry.aliases,
+    searchText: entry.texts.join("\n"),
+    updatedAt: entry.updatedAt,
+  }));
+}
+
+function extractProjectAliasFromText(text: string | undefined): string | null {
+  const firstMeaningfulLine = String(text ?? "")
+    .split(/\n+/u)
+    .map((line) => line.replace(/^#+\s*/u, "").trim())
+    .find(Boolean);
+  if (!firstMeaningfulLine) {
+    return null;
+  }
+  const normalized = firstMeaningfulLine
+    .replace(/^(product|optimization)\s+requirement[:：]\s*/iu, "")
+    .replace(/^implement\s+/iu, "")
+    .replace(/^design\s+/iu, "")
+    .replace(/^enhance\s+/iu, "")
+    .replace(/^qa[:\s-]+/iu, "")
+    .replace(/\s+(architecture|application|web app|workflows?|improvements?)$/iu, "")
+    .trim();
+  if (normalized.length < 4 || normalized.length > 80) {
+    return null;
+  }
+  return normalized;
+}
+
+function normalizeProjectMatchingText(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[`*_#:[\]()/\\-]+/gu, " ")
+    .replace(/\s+/gu, " ")
+    .trim();
+}
+
+function scoreProjectTokenOverlap(message: string, candidateText: string): number {
+  const messageTokens = tokenizeProjectMatchingText(message);
+  if (messageTokens.size === 0) {
+    return 0;
+  }
+  const candidateTokens = tokenizeProjectMatchingText(candidateText);
+  let overlap = 0;
+  for (const token of candidateTokens) {
+    if (messageTokens.has(token)) {
+      overlap += 1;
+    }
+  }
+  return overlap;
+}
+
+function tokenizeProjectMatchingText(text: string): Set<string> {
+  return new Set(
+    normalizeProjectMatchingText(text)
+      .split(" ")
+      .map((token) => token.trim())
+      .filter((token) => token.length >= 4 && !PROJECT_MATCH_STOPWORDS.has(token)),
+  );
+}
+
 function updateControllerRun(
   runId: string,
   deps: ControllerHttpDeps,
@@ -422,7 +671,6 @@ function serializeTask(task?: TaskInfo, includeExecutionEvents = false): Record<
   }
 
   const payload: Record<string, unknown> = { ...task };
-  delete payload.controllerSessionKey;
   if (!task.execution) {
     return payload;
   }
@@ -517,9 +765,10 @@ function normalizeControllerIntakeSessionKey(input: unknown): string {
     return fallback;
   }
 
-  return logicalKey.startsWith(CONTROLLER_INTAKE_SESSION_PREFIX)
+  const normalizedLogicalKey = logicalKey.startsWith(CONTROLLER_INTAKE_SESSION_PREFIX)
     ? logicalKey
     : `${CONTROLLER_INTAKE_SESSION_PREFIX}${logicalKey}`;
+  return buildTeamClawAgentSessionKey(normalizedLogicalKey);
 }
 
 async function withSerializedControllerIntake<T>(
@@ -693,6 +942,14 @@ function findLatestControllerRunIdForSession(
   return matchingRuns[0]?.id ?? null;
 }
 
+function resolveProjectDirForSession(
+  sessionKey: string,
+  state: TeamState | null,
+): string | undefined {
+  const runId = findLatestControllerRunIdForSession(sessionKey, state, { preferActive: true });
+  return runId ? state?.controllerRuns[runId]?.projectDir : undefined;
+}
+
 function resolveControllerWorkflowSessionKey(task: TaskInfo, state: TeamState | null): string | undefined {
   if (task.controllerSessionKey) {
     return normalizeControllerIntakeSessionKey(task.controllerSessionKey);
@@ -727,6 +984,9 @@ function buildControllerManifestEventMessage(manifest: ControllerOrchestrationMa
   if (manifest.clarificationsNeeded) {
     parts.push(`clarifications=${manifest.clarificationQuestions.length}`);
   }
+  if (manifest.requirementFullyComplete) {
+    parts.push("requirementFullyComplete=true");
+  }
   return parts.join(" ");
 }
 
@@ -781,6 +1041,16 @@ function buildControllerManifestReply(
     }
   }
 
+  // ── Team Kickoff Meeting (brief note; full details rendered in UI) ───
+  if (manifest.kickoffPlan?.assessments?.length) {
+    const kp = manifest.kickoffPlan;
+    const needed = kp.assessments.filter((a) => a.needed).length;
+    lines.push(
+      "",
+      `Team Kickoff Meeting: ${kp.assessments.length} roles assessed, ${needed} confirmed needed. See the Kickoff Meeting panel in the dashboard for full discussion details.`,
+    );
+  }
+
   if (manifest.handoffPlan) {
     lines.push("", `Handoff plan: ${manifest.handoffPlan}`);
   }
@@ -848,6 +1118,15 @@ function buildBackfilledControllerManifest(
   for (const roleId of inferManifestRolesFromText(rawReply)) {
     inferredRoles.add(roleId);
   }
+  for (const roleId of inferManifestRolesFromText(request)) {
+    inferredRoles.add(roleId);
+  }
+  // When no roles could be inferred at all (model didn't call the tool and didn't
+  // mention any role names), fall back to "developer" as the most general purpose role
+  // so that the intake run still has usable machine-readable state.
+  if (inferredRoles.size === 0) {
+    inferredRoles.add("developer");
+  }
   const clarificationQuestions = inferClarificationQuestionsFromReply(rawReply);
   return {
     version: "1.0",
@@ -855,6 +1134,12 @@ function buildBackfilledControllerManifest(
     requiredRoles: Array.from(inferredRoles),
     clarificationsNeeded: clarificationQuestions.length > 0 && actualCreatedTasks.length === 0,
     clarificationQuestions,
+    clarificationSchemas: clarificationQuestions.map((question) => ({
+      kind: "text",
+      title: question,
+      required: true,
+      placeholder: "Provide the missing information",
+    })),
     createdTasks: actualCreatedTasks.map((task) => ({
       title: task.title,
       assignedRole: task.assignedRole,
@@ -868,6 +1153,173 @@ function buildBackfilledControllerManifest(
   };
 }
 
+function looksLikeSoftwareRequirement(request: string): boolean {
+  const normalized = request.toLowerCase();
+  return /(api|backend|frontend|fastapi|react|vue|node|python|typescript|javascript|sql|database|service|app|web|mobile|docker|kubernetes|deploy|测试|系统|平台|接口|服务|数据库|应用|前端|后端)/.test(normalized);
+}
+
+function buildFallbackControllerTaskTitle(request: string, assignedRole?: RoleId): string {
+  const firstMeaningfulLine = request
+    .split(/\n+/)
+    .map((line) => line.replace(/^#+\s*/, "").trim())
+    .find(Boolean);
+  if (firstMeaningfulLine) {
+    const normalized = firstMeaningfulLine.replace(/^需求[:：]?\s*/, "").trim();
+    if (normalized.length > 0) {
+      const capped = normalized.slice(0, 72).trim();
+      return /[\u4e00-\u9fff]/.test(capped)
+        ? `实现${capped}`
+        : `Implement ${capped}`;
+    }
+  }
+  return assignedRole === "developer"
+    ? "Implement the requested software deliverable"
+    : `Perform the requested ${assignedRole || "software"} work`;
+}
+
+async function createControllerManagedTask(
+  input: {
+    title: string;
+    description: string;
+    priority?: TaskPriority;
+    assignedRole?: RoleId;
+    createdBy: string;
+    controllerSessionKey?: string;
+    recommendedSkills?: string[];
+  },
+  deps: ControllerHttpDeps,
+): Promise<TaskInfo | undefined> {
+  const taskId = generateId();
+  const now = Date.now();
+  const repoState = await refreshControllerRepoState(deps);
+  const normalizedSessionKey = input.createdBy === "controller" && input.controllerSessionKey
+    ? normalizeControllerIntakeSessionKey(input.controllerSessionKey)
+    : undefined;
+
+  let projectDir: string | undefined;
+  if (normalizedSessionKey) {
+    const runId = findLatestControllerRunIdForSession(normalizedSessionKey, deps.getTeamState(), { preferActive: true });
+    const parentRun = runId ? deps.getTeamState()?.controllerRuns[runId] : undefined;
+    projectDir = parentRun?.projectDir;
+  }
+  if (!projectDir) {
+    projectDir = deriveProjectSlug(input.title);
+  }
+
+  const normalizedRecommendedSkills = normalizeRecommendedSkills(input.recommendedSkills ?? []);
+  const task: TaskInfo = {
+    id: taskId,
+    title: input.title,
+    description: input.description,
+    status: "pending",
+    priority: input.priority ?? "medium",
+    assignedRole: input.assignedRole,
+    createdBy: input.createdBy,
+    recommendedSkills: normalizedRecommendedSkills.length > 0 ? normalizedRecommendedSkills : undefined,
+    controllerSessionKey: normalizedSessionKey,
+    projectDir,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  deps.updateTeamState((state) => {
+    state.tasks[taskId] = task;
+  });
+  recordTaskExecutionEvent(taskId, {
+    type: "lifecycle",
+    phase: "created",
+    source: "controller",
+    status: "pending",
+    message: `Task created by ${input.createdBy}.`,
+    role: input.assignedRole,
+  }, deps);
+  if (repoState?.enabled) {
+    recordTaskExecutionEvent(taskId, {
+      type: "lifecycle",
+      phase: "repo_ready",
+      source: "controller",
+      status: "pending",
+      message: repoState.remoteReady && repoState.remoteUrl
+        ? `Git collaboration ready on ${repoState.defaultBranch} with remote ${repoState.remoteUrl}.`
+        : `Git collaboration ready on ${repoState.defaultBranch} using controller-managed bundle sync.`,
+      role: input.assignedRole,
+    }, deps);
+  }
+  if (normalizedRecommendedSkills.length > 0) {
+    recordTaskExecutionEvent(taskId, {
+      type: "lifecycle",
+      phase: "skills_recommended",
+      source: "controller",
+      status: "pending",
+      message: `Recommended skills: ${normalizedRecommendedSkills.join(", ")}`,
+      role: input.assignedRole,
+    }, deps);
+  }
+
+  await autoAssignPendingTasks(deps);
+
+  const updatedTask = deps.getTeamState()?.tasks[taskId];
+  deps.wsServer.broadcastUpdate({ type: "task:created", data: serializeTask(updatedTask) });
+  return updatedTask;
+}
+
+async function maybeBackfillExecutionReadyTask(
+  controllerRunId: string,
+  sessionKey: string,
+  request: string,
+  manifest: ControllerOrchestrationManifest,
+  deps: ControllerHttpDeps,
+  options?: {
+    source?: ControllerRunSource;
+  },
+): Promise<string[]> {
+  if (manifest.createdTasks.length > 0 || manifest.clarificationsNeeded || manifest.requirementFullyComplete) {
+    return [];
+  }
+  if (options?.source === "task_follow_up") {
+    return [];
+  }
+  if (!looksLikeSoftwareRequirement(request)) {
+    return [];
+  }
+
+  const assignedRole = manifest.requiredRoles.includes("developer")
+    ? "developer"
+    : manifest.requiredRoles[0];
+  const task = await createControllerManagedTask({
+    title: buildFallbackControllerTaskTitle(request, assignedRole),
+    description: request,
+    assignedRole,
+    createdBy: "controller",
+    controllerSessionKey: sessionKey,
+    recommendedSkills: resolveRecommendedSkillsForRole(assignedRole, []),
+  }, deps);
+  if (!task) {
+    return [];
+  }
+
+  manifest.createdTasks = [{
+    title: task.title,
+    assignedRole: task.assignedRole,
+    expectedOutcome: summarizeManifestExpectedOutcome(task),
+  }];
+  manifest.notes = manifest.notes
+    ? `${manifest.notes} Controller synthesized a fallback execution-ready task because the model returned no created tasks.`
+    : "Controller synthesized a fallback execution-ready task because the model returned no created tasks.";
+  updateControllerRun(controllerRunId, deps, (run) => {
+    run.manifest = manifest;
+    appendControllerRunEvent(run, {
+      type: "warning",
+      phase: "task_backfilled",
+      source: "controller",
+      status: "running",
+      sessionKey,
+      message: `Controller synthesized fallback task ${task.id} (${task.assignedRole || "unassigned"}).`,
+    });
+  });
+  return [task.id];
+}
+
 function ensureControllerManifest(
   controllerRunId: string,
   sessionKey: string,
@@ -897,7 +1349,7 @@ function ensureControllerManifest(
   return manifest;
 }
 
-function buildControllerFollowUpMessage(task: TaskInfo): string {
+function buildControllerFollowUpMessage(task: TaskInfo, state: TeamState | null): string {
   const parts = [
     `A controller-created TeamClaw task has ${task.status === "failed" ? "failed" : "completed"}.`,
     `Task ID: ${task.id}`,
@@ -919,6 +1371,56 @@ function buildControllerFollowUpMessage(task: TaskInfo): string {
     parts.push("", "## Task Error", task.error);
   }
 
+  // Include preview URLs so the controller can present them to the human
+  if (task.resultContract?.deliverables) {
+    const liveDeliverables = task.resultContract.deliverables.filter((d) => d.liveUrl);
+    if (liveDeliverables.length > 0) {
+      parts.push("", "## Live Previews");
+      for (const d of liveDeliverables) {
+        parts.push(`- ${d.summary || d.value}: ${d.liveUrl}`);
+      }
+    }
+  }
+
+  // Inject prior manifest context (deferred tasks, clarification questions) so the
+  // controller knows the original plan and can advance it
+  if (state) {
+    const sessionKey = task.controllerSessionKey;
+    if (sessionKey) {
+      const priorRuns = Object.values(state.controllerRuns)
+        .filter((run) => normalizeControllerIntakeSessionKey(run.sessionKey) === normalizeControllerIntakeSessionKey(sessionKey) && run.manifest)
+        .sort((a, b) => b.updatedAt - a.updatedAt);
+
+      // Collect deferred tasks from the latest manifest that had them
+      const latestWithDeferred = priorRuns.find((run) => run.manifest!.deferredTasks && run.manifest!.deferredTasks.length > 0);
+      if (latestWithDeferred?.manifest?.deferredTasks) {
+        parts.push("", "## Prior Orchestration Plan (Deferred Tasks)");
+        parts.push("These tasks were identified in the original plan but deferred until prerequisites were met:");
+        for (const dt of latestWithDeferred.manifest.deferredTasks) {
+          const blockedBy = dt.blockedBy ? ` [blocked by: ${dt.blockedBy}]` : "";
+          parts.push(`- ${dt.title} (${dt.assignedRole || "any"})${blockedBy}`);
+        }
+      }
+
+      // Collect only still-pending clarification questions for this session.
+      const pendingClarifications = Object.values(state.clarifications)
+        .filter((clarification) =>
+          clarification.status === "pending"
+          && normalizeControllerIntakeSessionKey(clarification.controllerSessionKey) === normalizeControllerIntakeSessionKey(sessionKey),
+        )
+        .sort((a, b) => b.updatedAt - a.updatedAt);
+      const priorQuestions = pendingClarifications
+        .map((clarification) => clarification.question)
+        .filter(Boolean);
+      if (priorQuestions.length > 0) {
+        parts.push("", "## Prior Clarification Questions (from earlier runs)");
+        for (const q of priorQuestions.slice(0, 5)) {
+          parts.push(`- ${q}`);
+        }
+      }
+    }
+  }
+
   parts.push(
     "",
     "## Controller Follow-up",
@@ -926,12 +1428,184 @@ function buildControllerFollowUpMessage(task: TaskInfo): string {
     "Review the current TeamClaw state before acting.",
     "Create only the next execution-ready task(s) whose prerequisites are now satisfied.",
     "Do not duplicate tasks that already exist, are active, or are already completed.",
+    "If this task produced a web application with a live preview URL, include it in your reply so the human can verify the result.",
+    "If all planned phases are complete and no follow-ups remain, set requirementFullyComplete=true in the manifest and provide a final delivery summary.",
     "If no additional task should be created yet, reply briefly and stop.",
   );
 
   return parts.filter(Boolean).join("\n");
 }
 
+function buildControllerClarificationAnswerMessage(
+  clarification: ClarificationRequest,
+  answer: string,
+  answeredBy: string,
+): string {
+  return [
+    "The human has answered a pending controller clarification.",
+    `Question: ${clarification.question}`,
+    `Answer: ${answer}`,
+    `Answered by: ${answeredBy}`,
+    "Use this answer to continue the same requirement and update the plan/tasks accordingly.",
+  ].join("\n");
+}
+
+function buildStructuredClarificationAnswer(
+  clarification: ClarificationRequest,
+  payload: {
+    answer?: string;
+    answerValue?: string;
+    answerValues?: string[];
+    answerNumber?: number;
+    answerComment?: string;
+  },
+): string {
+  if (typeof payload.answer === "string" && payload.answer.trim()) {
+    return payload.answer.trim();
+  }
+  const schema = clarification.questionSchema;
+  const optionLabel = (value: string): string => {
+    const match = schema?.options?.find((entry) => entry.value === value);
+    return match?.label || value;
+  };
+  const parts: string[] = [];
+  if (schema?.kind === "single-select" && payload.answerValue) {
+    parts.push(optionLabel(payload.answerValue));
+  } else if (schema?.kind === "multi-select" && Array.isArray(payload.answerValues) && payload.answerValues.length > 0) {
+    parts.push(payload.answerValues.map((entry) => optionLabel(entry)).join(", "));
+  } else if (schema?.kind === "number" && typeof payload.answerNumber === "number" && Number.isFinite(payload.answerNumber)) {
+    parts.push(`${payload.answerNumber}${schema.unit ? ` ${schema.unit}` : ""}`);
+  } else if (payload.answerValue) {
+    parts.push(payload.answerValue);
+  }
+  if (payload.answerComment && payload.answerComment.trim()) {
+    parts.push(parts.length > 0 ? `Additional context: ${payload.answerComment.trim()}` : payload.answerComment.trim());
+  }
+  return parts.join("\n").trim();
+}
+
+function normalizeComparableText(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function buildManifestClarificationEntries(
+  manifest: ControllerOrchestrationManifest,
+): Array<{ question: string; questionSchema?: ClarificationRequest["questionSchema"] }> {
+  const normalizedQuestions = manifest.clarificationQuestions
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+  const schemas = Array.isArray(manifest.clarificationSchemas) ? manifest.clarificationSchemas : [];
+  if (schemas.length > 0) {
+    return schemas.map((schema, index) => ({
+      question: normalizedQuestions[index] || schema.title,
+      questionSchema: schema,
+    }));
+  }
+  return normalizedQuestions.map((question) => ({ question }));
+}
+
+function syncControllerRunClarifications(
+  controllerRunId: string,
+  sessionKey: string,
+  manifest: ControllerOrchestrationManifest,
+  deps: ControllerHttpDeps,
+): ClarificationRequest[] {
+  const entries = buildManifestClarificationEntries(manifest);
+  if (entries.length === 0) {
+    return [];
+  }
+
+  const created: ClarificationRequest[] = [];
+  const now = Date.now();
+  deps.updateTeamState((state) => {
+    const existingQuestions = new Map(
+      Object.values(state.clarifications)
+        .filter((item) => item.controllerRunId === controllerRunId)
+        .map((item) => [normalizeComparableText(item.question), item]),
+    );
+
+    for (const entry of entries) {
+      const key = normalizeComparableText(entry.question);
+      if (existingQuestions.has(key)) {
+        continue;
+      }
+      const clarification: ClarificationRequest = {
+        id: generateId(),
+        taskId: "",
+        controllerRunId,
+        controllerSessionKey: sessionKey,
+        requestedBy: "controller",
+        question: entry.question,
+        questionSchema: entry.questionSchema,
+        blockingReason: "The controller needs this information before it can confidently continue planning and downstream task creation.",
+        context: manifest.requirementSummary,
+        status: "pending",
+        createdAt: now,
+        updatedAt: now,
+      };
+      state.clarifications[clarification.id] = clarification;
+      created.push(clarification);
+    }
+  });
+
+  for (const clarification of created) {
+    deps.wsServer.broadcastUpdate({ type: "clarification:requested", data: clarification });
+  }
+  return created;
+}
+
+function reconcileControllerClarifications(deps: ControllerHttpDeps): TeamState | null {
+  const state = deps.getTeamState();
+  if (!state) {
+    return null;
+  }
+
+  deps.updateTeamState((draft) => {
+    const runsBySession = new Map<string, ControllerRunInfo[]>();
+    for (const run of Object.values(draft.controllerRuns)) {
+      const normalizedSessionKey = normalizeControllerIntakeSessionKey(run.sessionKey);
+      const bucket = runsBySession.get(normalizedSessionKey) ?? [];
+      bucket.push(run);
+      runsBySession.set(normalizedSessionKey, bucket);
+    }
+
+    for (const clar of Object.values(draft.clarifications)) {
+      if (clar.status !== "pending" || clar.requestedBy !== "controller" || clar.taskId) {
+        continue;
+      }
+      const normalizedSessionKey = normalizeControllerIntakeSessionKey(clar.controllerSessionKey);
+      const sessionRuns = runsBySession.get(normalizedSessionKey) ?? [];
+      const supersedingRun = sessionRuns.find((run) =>
+        run.updatedAt > clar.updatedAt
+        && (
+          run.manifest?.createdTasks.length
+          || run.manifest?.requirementFullyComplete
+        ),
+      );
+      if (!supersedingRun) {
+        continue;
+      }
+      clar.status = "answered";
+      clar.answer = "Automatically superseded by later controller progress.";
+      clar.answeredBy = "system";
+      clar.answeredAt = supersedingRun.updatedAt;
+      clar.updatedAt = supersedingRun.updatedAt;
+    }
+  });
+
+  for (const run of Object.values(state.controllerRuns)) {
+    if (!run.manifest?.clarificationsNeeded) {
+      continue;
+    }
+    syncControllerRunClarifications(run.id, run.sessionKey, run.manifest, deps);
+  }
+
+  return deps.getTeamState();
+}
+
 function buildControllerRateLimitProbeMessage(
   sourceTaskId?: string,
   sourceTaskTitle?: string,
@@ -949,6 +1623,64 @@ function buildControllerRateLimitProbeMessage(
   ].join("\n");
 }
 
+function buildControllerInactivityProbeMessage(
+  inactivityMs: number,
+  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}.`,
+    `There has been no new visible controller workflow progress for over ${formatDuration(inactivityMs)}.`,
+    "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 checkAndGenerateReport(task: TaskInfo, deps: ControllerHttpDeps): Promise<void> {
+  const sessionKey = task.controllerSessionKey;
+  if (!sessionKey) return;
+
+  const state = deps.getTeamState();
+  if (!state) return;
+
+  if (!isSessionComplete(sessionKey, state, normalizeControllerIntakeSessionKey)) return;
+
+  const report = generateDeliveryReport(sessionKey, state, normalizeControllerIntakeSessionKey);
+  if (!report) return;
+
+  // Check if we already generated a report for this session
+  const existingReport = state.reports?.[report.id];
+  if (existingReport) return;
+
+  // Store a lightweight record in state (full report is generated on demand from live state)
+  deps.updateTeamState((s) => {
+    if (!s.reports) s.reports = {};
+    s.reports[report.id] = {
+      id: report.id,
+      sessionKey: report.sessionKey,
+      generatedAt: report.generatedAt,
+      projectName: report.projectName,
+      requirementSummary: report.requirementSummary,
+      status: report.status,
+      taskCount: report.taskCount,
+      deliverableCount: report.deliverables.length,
+      previewCount: report.deliverables.filter((d) => d.previewUrl).length,
+    };
+  });
+
+  const reportUrl = `/api/v1/reports/${encodeURIComponent(sessionKey)}`;
+  deps.wsServer.broadcastUpdate({
+    type: "report:ready",
+    data: { sessionKey, reportUrl, projectName: report.projectName, status: report.status },
+  });
+  deps.logger.info(`Controller: delivery report generated for session ${sessionKey}: ${reportUrl}`);
+}
+
 async function continueControllerWorkflow(task: TaskInfo, deps: ControllerHttpDeps): Promise<void> {
   if (task.createdBy !== "controller") {
     return;
@@ -965,7 +1697,7 @@ async function continueControllerWorkflow(task: TaskInfo, deps: ControllerHttpDe
       }
     });
   }
-  await runControllerIntake(buildControllerFollowUpMessage(task), sessionKey, deps, {
+  await runControllerIntake(buildControllerFollowUpMessage(task, deps.getTeamState()), sessionKey, deps, {
     source: "task_follow_up",
     sourceTaskId: task.id,
     sourceTaskTitle: task.title,
@@ -983,9 +1715,32 @@ async function runControllerIntake(
   },
 ): Promise<{ sessionKey: string; runId: string; reply: string; controllerRunId: string }> {
   const normalizedSessionKey = normalizeControllerIntakeSessionKey(sessionKey);
-  return withSerializedControllerIntake(normalizedSessionKey, () =>
-    runControllerIntakeUnlocked(message, normalizedSessionKey, deps, options),
-  );
+  return withSerializedControllerIntake(normalizedSessionKey, async () => {
+    let lastError: Error | null = null;
+    for (let attempt = 0; attempt <= CONTROLLER_INTAKE_MAX_RETRIES; attempt++) {
+      try {
+        return await runControllerIntakeUnlocked(message, normalizedSessionKey, deps, options);
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        const errorText = lastError.message;
+        // Only retry on transient server errors (500/502/503), not on client errors,
+        // timeouts, or other failures that retrying won't fix.
+        if (
+          attempt === CONTROLLER_INTAKE_MAX_RETRIES
+          || !CONTROLLER_INTAKE_RETRYABLE_ERROR_PATTERN.test(errorText)
+          || errorText.includes("timed out")
+        ) {
+          throw lastError;
+        }
+        // Record a visible retry event so the human can see what happened.
+        deps.logger.warn(
+          `Controller: intake attempt ${attempt + 1} failed with transient error: ${errorText.slice(0, 200)}. Retrying in ${CONTROLLER_INTAKE_RETRY_DELAY_MS * (attempt + 1) / 1000}s...`,
+        );
+        await new Promise<void>((resolve) => setTimeout(resolve, CONTROLLER_INTAKE_RETRY_DELAY_MS * (attempt + 1)));
+      }
+    }
+    throw lastError!;
+  });
 }
 
 async function runControllerIntakeUnlocked(
@@ -1034,6 +1789,16 @@ async function runControllerIntakeUnlocked(
     active: false,
     probeCount: 0,
   };
+  const inactivityState: {
+    active: boolean;
+    visibleAt?: number;
+    nextProbeAt?: number;
+    probeCount: number;
+  } = {
+    active: false,
+    nextProbeAt: Date.now() + deps.config.taskTimeoutMs,
+    probeCount: 0,
+  };
 
   const markRateLimitWaiting = async (): Promise<void> => {
     if (rateLimitState.active) {
@@ -1060,6 +1825,12 @@ async function runControllerIntakeUnlocked(
     rateLimitState.nextProbeAt = undefined;
   };
 
+  const noteObservedControllerActivity = (): void => {
+    inactivityState.active = false;
+    inactivityState.visibleAt = undefined;
+    inactivityState.nextProbeAt = Date.now() + deps.config.taskTimeoutMs;
+  };
+
   const extractSessionAssistantReply = async (): Promise<string> => {
     const sessionMessages = await deps.runtime.subagent.getSessionMessages({
       sessionKey,
@@ -1113,19 +1884,76 @@ async function runControllerIntakeUnlocked(
     }
 
     clearRateLimitWaiting();
+    noteObservedControllerActivity();
+    return probeReply;
+  };
+
+  const probeInactiveControllerCompletion = async (): Promise<string | null> => {
+    inactivityState.probeCount += 1;
+    const now = Date.now();
+    inactivityState.active = true;
+    inactivityState.visibleAt = now;
+    inactivityState.nextProbeAt = now + deps.config.taskTimeoutMs;
+    recordControllerRunEvent(controllerRun.id, {
+      type: "progress",
+      phase: "inactivity_probe",
+      source: "controller",
+      status: "running",
+      sessionKey,
+      runId: runResult.runId,
+      message: `No new controller workflow output has appeared for over ${formatDuration(deps.config.taskTimeoutMs)}. Re-checking whether this orchestration step is complete or still running.`,
+    }, deps);
+
+    const probeRun = await deps.runtime.subagent.run({
+      sessionKey,
+      message: buildControllerInactivityProbeMessage(
+        deps.config.taskTimeoutMs,
+        options?.sourceTaskId,
+        options?.sourceTaskTitle,
+      ),
+      extraSystemPrompt: buildControllerIntakeSystemPrompt(deps),
+      idempotencyKey: `${runResult.runId}:inactivity-probe:${inactivityState.probeCount}`,
+    });
+    const probeWait = await deps.runtime.subagent.waitForRun({
+      runId: probeRun.runId,
+      timeoutMs: CONTROLLER_INACTIVITY_PROBE_TIMEOUT_MS,
+    });
+
+    if (probeWait.status === "error" && isRateLimitMessage(probeWait.error || "")) {
+      await markRateLimitWaiting();
+      return null;
+    }
+    if (probeWait.status !== "ok") {
+      return null;
+    }
+
+    const probeReply = await extractSessionAssistantReply();
+    if (!probeReply || isRateLimitMessage(probeReply) || isStillWaitingResponse(probeReply)) {
+      inactivityState.active = false;
+      inactivityState.visibleAt = undefined;
+      inactivityState.nextProbeAt = Date.now() + deps.config.taskTimeoutMs;
+      recordControllerRunEvent(controllerRun.id, {
+        type: "progress",
+        phase: "inactivity_still_waiting",
+        source: "controller",
+        status: "running",
+        sessionKey,
+        runId: runResult.runId,
+        message: "The controller workflow is still running without a final result yet. TeamClaw will keep waiting instead of failing the run.",
+      }, deps);
+      return null;
+    }
+
+    if (rateLimitState.active) {
+      clearRateLimitWaiting();
+    }
+    noteObservedControllerActivity();
     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) {
@@ -1134,14 +1962,22 @@ async function runControllerIntakeUnlocked(
       }
     }
 
-    const sliceTimeoutMs = Math.max(1_000, Math.min(CONTROLLER_RUN_WAIT_SLICE_MS, remainingMs));
+    if (!rateLimitState.active && (inactivityState.nextProbeAt ?? Number.POSITIVE_INFINITY) <= Date.now()) {
+      completionOverride = await probeInactiveControllerCompletion();
+      if (completionOverride) {
+        waitResult = { status: "ok" };
+        break;
+      }
+    }
+
     waitResult = await deps.runtime.subagent.waitForRun({
       runId: runResult.runId,
-      timeoutMs: sliceTimeoutMs,
+      timeoutMs: CONTROLLER_RUN_WAIT_SLICE_MS,
     });
 
     if (waitResult.status === "ok") {
       clearRateLimitWaiting();
+      noteObservedControllerActivity();
       break;
     }
     if (waitResult.status === "error") {
@@ -1152,24 +1988,6 @@ async function runControllerIntakeUnlocked(
       break;
     }
   }
-
-  if (waitResult.status === "timeout") {
-    const createdTaskIds = tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
-    updateControllerRun(controllerRun.id, deps, (run) => {
-      run.createdTaskIds = createdTaskIds;
-      run.error = "Controller intake timed out";
-      appendControllerRunEvent(run, {
-        type: "error",
-        phase: "timeout",
-        source: "controller",
-        status: "failed",
-        sessionKey,
-        runId: runResult.runId,
-        message: "Controller intake timed out.",
-      });
-    });
-    throw new Error("Controller intake timed out");
-  }
   if (waitResult.status !== "ok") {
     const errorMessage = waitResult.error || "Controller intake failed";
     const createdTaskIds = tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
@@ -1189,7 +2007,7 @@ async function runControllerIntakeUnlocked(
     throw new Error(errorMessage);
   }
 
-  const createdTaskIds = tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
+  let createdTaskIds = tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
 
   const rawReply = completionOverride || await extractSessionAssistantReply()
     || "Controller completed the intake run but did not return any text.";
@@ -1201,7 +2019,88 @@ async function runControllerIntakeUnlocked(
     createdTaskIds,
     deps,
   );
+  const fallbackTaskIds = await maybeBackfillExecutionReadyTask(
+    controllerRun.id,
+    sessionKey,
+    message,
+    recordedManifest,
+    deps,
+    { source: options?.source },
+  );
+  if (fallbackTaskIds.length > 0) {
+    createdTaskIds = Array.from(new Set([...createdTaskIds, ...fallbackTaskIds]));
+  }
+  syncControllerRunClarifications(controllerRun.id, sessionKey, recordedManifest, deps);
   const reconciledTasks = reconcileControllerManifestTaskBindings(sessionKey, createdTaskIds, recordedManifest, deps);
+
+  // ── Automatic Team Kickoff ────────────────────────────────────────────
+  // For complex projects (3+ roles), automatically run a kickoff meeting
+  // so every candidate role can assess the requirement collaboratively.
+  // This happens AFTER the initial LLM pass so we know which roles are
+  // needed, but we store the assessments for visibility and future
+  // refinement passes.
+  const AUTO_KICKOFF_ROLE_THRESHOLD = 3;
+  const isFollowUp = options?.source === "task_follow_up";
+  const kickoffHandler = deps.getKickoffHandler?.();
+  if (
+    !isFollowUp
+    && kickoffHandler
+    && recordedManifest.requiredRoles.length >= AUTO_KICKOFF_ROLE_THRESHOLD
+    && !recordedManifest.clarificationsNeeded
+  ) {
+    deps.logger.info(
+      `Controller: auto-kickoff triggered for ${recordedManifest.requiredRoles.length} roles: ${recordedManifest.requiredRoles.join(", ")}`,
+    );
+    recordControllerRunEvent(controllerRun.id, {
+      type: "lifecycle",
+      phase: "kickoff_started",
+      source: "controller",
+      status: "running",
+      sessionKey,
+      message: `Auto-kickoff: provisioning ${recordedManifest.requiredRoles.length} candidate roles for team assessment.`,
+    }, deps);
+    try {
+      const kickoffResult = await kickoffHandler(
+        recordedManifest.requiredRoles as RoleId[],
+        recordedManifest.requiredRoles.length >= 5 ? "complex" : "medium",
+        message,
+      );
+      // Store kickoff assessments on the manifest for UI/API visibility
+      recordedManifest.kickoffPlan = {
+        assessments: kickoffResult.assessments,
+        summary: kickoffResult.summary,
+        triggeredAt: Date.now(),
+      };
+      updateControllerRun(controllerRun.id, deps, (run) => {
+        if (run.manifest) {
+          run.manifest.kickoffPlan = recordedManifest.kickoffPlan;
+        }
+        appendControllerRunEvent(run, {
+          type: "lifecycle",
+          phase: "kickoff_completed",
+          source: "controller",
+          status: "running",
+          sessionKey,
+          message: `Team kickoff completed: ${kickoffResult.assessments.length} assessments collected. ${kickoffResult.summary.slice(0, 200)}`,
+        });
+      });
+      deps.logger.info(
+        `Controller: auto-kickoff completed with ${kickoffResult.assessments.length} assessments`,
+      );
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      deps.logger.warn(`Controller: auto-kickoff failed: ${errMsg}`);
+      recordControllerRunEvent(controllerRun.id, {
+        type: "lifecycle",
+        phase: "kickoff_failed",
+        source: "controller",
+        status: "running",
+        sessionKey,
+        message: `Auto-kickoff failed: ${errMsg}. Proceeding with controller-only planning.`,
+      }, deps);
+    }
+  }
+
   const latestTeamState = deps.getTeamState();
   const reply = buildControllerManifestReply(recordedManifest, reconciledTasks.taskIds, latestTeamState, rawReply);
 
@@ -1283,8 +2182,15 @@ function buildRecentCompletedTaskContext(task: TaskInfo, state: TeamState | null
     return "";
   }
 
+  // Only include tasks from the same session/project to avoid cross-project contamination.
+  // Tasks sharing the same controllerSessionKey belong to the same user requirement.
+  const sameSession = task.controllerSessionKey
+    ? (candidate: TaskInfo) => candidate.controllerSessionKey === task.controllerSessionKey
+    : () => true; // If no session key, fall back to all completed tasks (legacy behavior)
+
   const recentCompletedTasks = Object.values(state.tasks)
     .filter((candidate) => candidate.id !== task.id && candidate.status === "completed")
+    .filter(sameSession)
     .filter((candidate) => (candidate.completedAt ?? candidate.updatedAt) <= task.createdAt)
     .sort((a, b) => (b.completedAt ?? b.updatedAt) - (a.completedAt ?? a.updatedAt))
     .slice(0, MAX_RECENT_TASK_CONTEXT)
@@ -1325,10 +2231,18 @@ function buildRecommendedSkillsContext(task: TaskInfo): string {
 
 function buildTaskAssignmentDescription(task: TaskInfo, state: TeamState | null, repoInfo?: RepoSyncInfo): string {
   const parts = [task.description];
+  const projectContext = buildProjectDirectoryContext(task.projectDir);
+  if (projectContext) {
+    parts.push("", projectContext);
+  }
   const recommendedSkillsContext = buildRecommendedSkillsContext(task);
   if (recommendedSkillsContext) {
     parts.push("", recommendedSkillsContext);
   }
+  const patternsContext = buildConsolidatedPatternsContext();
+  if (patternsContext) {
+    parts.push("", patternsContext);
+  }
   const recentContext = buildRecentCompletedTaskContext(task, state);
   if (recentContext) {
     parts.push("", recentContext);
@@ -1339,6 +2253,21 @@ function buildTaskAssignmentDescription(task: TaskInfo, state: TeamState | null,
   return parts.join("\n");
 }
 
+function buildProjectDirectoryContext(projectDir?: string): string | null {
+  if (!projectDir) {
+    return null;
+  }
+  const workspaceRelativePath = buildTeamClawProjectWorkspacePath(projectDir);
+  const absoluteProjectPath = path.join(resolveTeamClawProjectsDir(), projectDir).replace(/\\/gu, "/");
+  return [
+    "## Authoritative Project Paths",
+    `- Workspace-relative project path: \`${workspaceRelativePath}/\``,
+    `- Absolute project path: \`${absoluteProjectPath}/\``,
+    "- If the task description mentions any other workspace path, treat it as stale text from an older layout.",
+    "- Resolve project-local files (for example `ARCHITECTURE.md`, `README.md`, `package.json`, `data/...`) inside the authoritative project path above.",
+  ].join("\n");
+}
+
 function buildRepoTaskContext(repoInfo: RepoSyncInfo): string {
   const lines = [
     "## TeamClaw Git Collaboration",
@@ -1465,20 +2394,16 @@ async function cancelTaskExecution(
   }
 
   let cancelled = false;
-  if (deps.localWorkerManager?.isLocalWorkerId(workerId)) {
-    cancelled = await deps.localWorkerManager.cancelTaskExecution(workerId, taskId);
-  } else {
-    try {
-      const res = await fetch(`${worker.url}/api/v1/tasks/${taskId}/cancel`, {
-        method: "POST",
-      });
-      cancelled = res.ok;
-      if (!res.ok) {
-        deps.logger.warn(`Controller: worker cancel failed for ${taskId} on ${workerId} (${res.status})`);
-      }
-    } catch (err) {
-      deps.logger.warn(`Controller: failed to cancel task ${taskId} on ${workerId}: ${String(err)}`);
+  try {
+    const res = await fetch(`${worker.url}/api/v1/tasks/${taskId}/cancel`, {
+      method: "POST",
+    });
+    cancelled = res.ok;
+    if (!res.ok) {
+      deps.logger.warn(`Controller: worker cancel failed for ${taskId} on ${workerId} (${res.status})`);
     }
+  } catch (err) {
+    deps.logger.warn(`Controller: failed to cancel task ${taskId} on ${workerId}: ${String(err)}`);
   }
 
   if (!cancelled) {
@@ -1511,11 +2436,308 @@ function workspaceRequestErrorStatus(err: unknown): number {
   if (err && typeof err === "object" && "code" in err && (err as { code?: unknown }).code === "ENOENT") {
     return 404;
   }
-  return 400;
+  return 400;
+}
+
+function workspaceRequestErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : "Workspace request failed";
+}
+
+function getEffectiveStartupReadiness(
+  deps: ControllerHttpDeps,
+  state: TeamState | null,
+): StartupProvisioningReadiness | null {
+  if (!deps.workerProvisioningManager?.isEnabled()) {
+    return null;
+  }
+  const requiredRoles = deps.config.workerProvisioningRoles.length > 0
+    ? [...new Set(deps.config.workerProvisioningRoles)]
+    : ["developer"];
+  const readyWorkerIds = requiredRoles
+    .map((role) => Object.values(state?.workers ?? {}).find((worker) =>
+      worker.role === role && (worker.status === "idle" || worker.status === "busy")
+    )?.id)
+    .filter((workerId): workerId is string => Boolean(workerId));
+
+  if (readyWorkerIds.length === requiredRoles.length) {
+    const recorded = state?.provisioning?.startupReadiness;
+    return {
+      status: "ready",
+      startedAt: recorded?.startedAt ?? state?.createdAt ?? Date.now(),
+      checkedAt: Date.now(),
+      attempts: recorded?.attempts ?? 0,
+      requiredRoles,
+      readyWorkerIds,
+      message: recorded?.status === "ready"
+        ? recorded.message
+        : `Startup provisioning ready with ${readyWorkerIds.length} warm worker(s).`,
+    };
+  }
+
+  return state?.provisioning?.startupReadiness ?? {
+    status: "checking",
+    startedAt: state?.createdAt ?? Date.now(),
+    checkedAt: Date.now(),
+    attempts: 0,
+    requiredRoles,
+    readyWorkerIds,
+    message: `Startup provisioning warm-up is still initializing for ${requiredRoles.join(", ")}.`,
+  };
+}
+
+function buildStartupReadinessMessage(readiness: StartupProvisioningReadiness): string {
+  const requiredRoles = readiness.requiredRoles.length > 0 ? readiness.requiredRoles.join(", ") : "configured startup roles";
+  if (readiness.status === "ready") {
+    return readiness.message ?? "Startup provisioning is ready.";
+  }
+  if (readiness.status === "checking") {
+    return readiness.message ?? `Startup provisioning is still warming workers for ${requiredRoles}.`;
+  }
+  return readiness.message ?? `Startup provisioning is degraded for ${requiredRoles}. Check provisioning logs and fix worker startup before retrying.`;
+}
+
+function shouldBlockControllerUntilProvisioningReady(
+  deps: ControllerHttpDeps,
+  state: TeamState | null,
+): { blocked: boolean; readiness: StartupProvisioningReadiness | null } {
+  const readiness = getEffectiveStartupReadiness(deps, state);
+  if (!readiness) {
+    return { blocked: false, readiness: null };
+  }
+  return {
+    blocked: readiness.status !== "ready",
+    readiness,
+  };
+}
+
+/**
+ * Filter deliverables that don't belong to the current task's project directory.
+ * This prevents cross-project contamination when the model references stale files
+ * from previous sessions visible in the shared workspace.
+ */
+function filterStaleDeliverables(
+  contract: WorkerTaskResultContract,
+  taskProjectDir: string | undefined,
+): WorkerTaskResultContract {
+  if (!taskProjectDir) return contract;
+  // Normalize: "projects/foo-bar/" → "projects/foo-bar"
+  const normalizedDir = taskProjectDir.replace(/\/$/u, "");
+  const filtered = contract.deliverables.filter((d) => {
+    const val = (d.value ?? "").replace(/\/$/u, "");
+    if (!val) return true; // keep notes/commands without paths
+    if (d.kind === "note" || d.kind === "command") return true;
+    // Accept deliverables whose path contains the projectDir or is rooted in teamclaw/projects/{projectDir}
+    if (val.includes(normalizedDir)) return true;
+    // Accept relative paths that look like project-internal (no slashes or relative)
+    if (!val.includes("/") || val.startsWith("./")) return true;
+    // Reject paths from other project directories
+    return false;
+  });
+  if (filtered.length === contract.deliverables.length) return contract;
+  return { ...contract, deliverables: filtered };
+}
+
+/**
+ * Strategy 4: When text-based enrichment found no HTML file references,
+ * scan the workspace filesystem for HTML files and create a web-app deliverable.
+ * This handles workers that return abstract summaries without mentioning specific paths.
+ */
+function enrichWithFilesystemHtmlScan(
+  contract: WorkerTaskResultContract,
+  taskProjectDir?: string,
+): WorkerTaskResultContract | null {
+  const existingWebApp = contract.deliverables.find((d) => d.artifactType === "web-app");
+  if (existingWebApp) {
+    const cwd = existingWebApp.previewCwd?.trim();
+    if (cwd && cwd !== "." && cwd !== "./") {
+      return null;
+    }
+    // Fall through — existing web-app has root previewCwd, try to improve it
+  }
+
+  let workspaceDir: string;
+  let openclawWorkspaceDir: string;
+  try {
+    workspaceDir = resolveTeamClawWorkspaceDir();
+    openclawWorkspaceDir = resolveTeamClawAgentWorkspaceRootDir();
+  } catch {
+    return null;
+  }
+
+  // Recursively scan the workspace for HTML files (up to 3 levels deep)
+  const MAX_DEPTH = 3;
+  const htmlCandidates: { dirPath: string; filename: string }[] = [];
+
+  function scanDir(dir: string, depth: number) {
+    if (depth > MAX_DEPTH) return;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === ".git") continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        scanDir(fullPath, depth + 1);
+      } else if (entry.isFile() && (entry.name.endsWith(".html") || entry.name.endsWith(".htm"))) {
+        if (!entry.name.includes(".config.") && !entry.name.includes(".test.") && !entry.name.includes(".spec.")) {
+          htmlCandidates.push({ dirPath: dir, filename: entry.name });
+        }
+      }
+    }
+  }
+
+  // Scope scan to the task's project directory when available to avoid
+  // picking up stale HTML from unrelated projects.
+  const scanRoot = taskProjectDir
+    ? path.join(workspaceDir, taskProjectDir)
+    : workspaceDir;
+  if (taskProjectDir && !fs.existsSync(scanRoot)) {
+    return null;
+  }
+  scanDir(scanRoot, 0);
+
+  if (htmlCandidates.length === 0) {
+    return null;
+  }
+
+  // Use OpenClaw workspace root as base for relative paths (worker paths and
+  // preview manager both resolve relative to the OpenClaw workspace, not the
+  // TeamClaw subdirectory).
+  const candidate = htmlCandidates[0];
+  const relativeDir = path.relative(openclawWorkspaceDir, candidate.dirPath) || ".";
+  const normalizedDir = relativeDir.replace(/\\/gu, "/");
+
+  // Avoid adding a duplicate if a directory deliverable for this path already exists
+  const existingDir = contract.deliverables.find(
+    (d) => d.kind === "directory" && d.value.replace(/\\/gu, "/").replace(/\/$/u, "") === normalizedDir,
+  );
+  if (existingDir && existingDir.artifactType === "web-app" && existingWebApp?.previewCwd?.trim() !== ".") {
+    // Existing web-app already has a specific, non-root directory — leave it alone.
+    return null;
+  }
+
+  const newDeliverable: WorkerTaskResultDeliverable = {
+    kind: "directory",
+    value: normalizedDir,
+    summary: `Web application at ${normalizedDir}`,
+    artifactType: "web-app",
+    previewCommand: "npx -y serve -l {PORT}",
+    previewCwd: normalizedDir,
+    previewReadyPath: "/",
+  };
+
+  const newDeliverables = [...contract.deliverables];
+  if (existingDir) {
+    // Update existing directory deliverable with web-app fields
+    const idx = newDeliverables.indexOf(existingDir);
+    // Always take the filesystem scan's directory path, which is more specific
+    newDeliverables[idx] = { ...existingDir, ...newDeliverable };
+  } else {
+    newDeliverables.push(newDeliverable);
+  }
+
+  return { ...contract, deliverables: newDeliverables };
+}
+
+const MEANINGFUL_PROJECT_CHANGE_EXTENSIONS = new Set([
+  ".js", ".jsx", ".ts", ".tsx", ".json", ".html", ".css", ".scss", ".md", ".txt", ".yml", ".yaml",
+]);
+
+const IGNORED_PROJECT_CHANGE_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", ".cache", "coverage", "tmp", "temp",
+]);
+
+const IGNORED_PROJECT_CHANGE_FILES = new Set([
+  "package-lock.json", "pnpm-lock.yaml", "yarn.lock",
+]);
+
+function taskRequiresMeaningfulProjectChangeGate(task: TaskInfo): boolean {
+  if (task.assignedRole !== "developer" || !task.projectDir) {
+    return false;
+  }
+  const text = `${task.title}\n${task.description}`.toLowerCase();
+  if (/\b(qa|audit|review|verify|verification|validate|test|retest|confirm|check)\b/u.test(text)) {
+    return false;
+  }
+  if (/(审计|审核|验证|复检|复查|确认|测试|检查)/u.test(text)) {
+    return false;
+  }
+  return /\b(implement|build|fix|rework|update|add|enhanc|deliver|write|create)\b/u.test(text);
+}
+
+function projectHasMeaningfulFileChanges(task: TaskInfo): boolean {
+  if (!task.projectDir) {
+    return false;
+  }
+  const projectRoot = path.join(resolveTeamClawProjectsDir(), task.projectDir);
+  if (!fs.existsSync(projectRoot)) {
+    return false;
+  }
+  const threshold = Math.max(task.startedAt ?? 0, task.createdAt ?? 0) - 1000;
+  const stack = [projectRoot];
+  while (stack.length > 0) {
+    const currentDir = stack.pop()!;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!IGNORED_PROJECT_CHANGE_DIRS.has(entry.name)) {
+          stack.push(path.join(currentDir, entry.name));
+        }
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (IGNORED_PROJECT_CHANGE_FILES.has(entry.name)) {
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!MEANINGFUL_PROJECT_CHANGE_EXTENSIONS.has(ext)) {
+        continue;
+      }
+      const fullPath = path.join(currentDir, entry.name);
+      try {
+        const stats = fs.statSync(fullPath);
+        if (stats.mtimeMs >= threshold) {
+          return true;
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  return false;
 }
 
-function workspaceRequestErrorMessage(err: unknown): string {
-  return err instanceof Error ? err.message : "Workspace request failed";
+function allowsNoChangeCompletion(
+  task: TaskInfo,
+  contract: WorkerTaskResultContract | undefined,
+  resultText: string,
+): boolean {
+  const taskText = `${task.title}\n${task.description}`.toLowerCase();
+  const evidenceText = [
+    contract?.summary ?? "",
+    contract?.notes ?? "",
+    ...(contract?.keyPoints ?? []),
+    resultText,
+  ].join("\n").toLowerCase();
+  const hasVerificationEvidence =
+    (contract?.deliverables ?? []).some((deliverable) => deliverable.kind === "command" || deliverable.kind === "note")
+    || /\b(go test|go vet|npm test|pnpm test|yarn test|pytest|cargo test|verified|verification|passes|all tests pass|no remaining)\b/u.test(evidenceText);
+  const noChangeIsExpected =
+    /\b(qa|audit|review|verify|verification|validate|test|retest|confirm|check)\b/u.test(taskText)
+    || /(审计|审核|验证|复检|复查|确认|测试|检查)/u.test(taskText)
+    || /\b(already fixed|already resolved|no further changes|no code changes|no file changes|no additional changes|verified existing fix)\b/u.test(evidenceText)
+    || /(已修复|已解决|无需改动|无需修改|没有额外修改|无需额外变更|只需验证)/u.test(evidenceText);
+  return hasVerificationEvidence && noChangeIsExpected;
 }
 
 function applyTaskResult(
@@ -1536,6 +2758,19 @@ function applyTaskResult(
     task.error = error;
     task.completedAt = Date.now();
     task.updatedAt = Date.now();
+    // Re-enrich deliverables now that the full result text is available.
+    if (!error && task.resultContract) {
+      // Filter out stale deliverables from other projects first
+      task.resultContract = filterStaleDeliverables(task.resultContract, task.projectDir);
+      let enriched = enrichDeliverablesWithPreviewInference(task.resultContract, result);
+      if (!enriched) {
+        // Text-based enrichment failed — scan the workspace filesystem for HTML files.
+        enriched = enrichWithFilesystemHtmlScan(task.resultContract, task.projectDir);
+      }
+      if (enriched) {
+        task.resultContract = enriched;
+      }
+    }
     completionEvent = appendTaskExecutionEvent(task, {
       type: error ? "error" : "lifecycle",
       phase: error ? "result_failed" : "result_completed",
@@ -1583,13 +2818,111 @@ function applyTaskResult(
         logger.warn(
           `Controller: failed to continue intake workflow after ${taskId}: ${String(err)}`,
         );
+      }).finally(() => {
+        // After the follow-up run completes (or if there was none), check session completion.
+        void checkAndGenerateReport(updatedTask, deps).catch(() => {});
       });
+    } else if (updatedTask.controllerSessionKey) {
+      // Non-controller tasks or failed tasks — still check session completion.
+      void checkAndGenerateReport(updatedTask, deps).catch(() => {});
     }
   }
 
   return updatedTask;
 }
 
+async function requestTaskClarification(params: {
+  taskId: string;
+  requestedBy: string;
+  requestedByWorkerId?: string;
+  requestedByRole?: RoleId;
+  question: string;
+  blockingReason: string;
+  context?: string;
+  questionSchema?: ClarificationRequest["questionSchema"];
+}, deps: ControllerHttpDeps): Promise<{
+  status: "created" | "already-pending" | "conflict" | "missing-task";
+  clarification?: ClarificationRequest;
+  task?: TaskInfo;
+}> {
+  const { getTeamState, updateTeamState, wsServer } = deps;
+  const currentState = getTeamState();
+  const currentTask = currentState?.tasks[params.taskId];
+  if (!currentTask) {
+    return { status: "missing-task" };
+  }
+
+  if (currentTask.clarificationRequestId) {
+    const existing = currentState?.clarifications[currentTask.clarificationRequestId];
+    if (existing?.status === "pending") {
+      return { status: "already-pending", clarification: existing, task: currentTask };
+    }
+  }
+
+  if (currentTask.status === "completed" || currentTask.status === "failed") {
+    return { status: "conflict", task: currentTask };
+  }
+
+  const previousWorkerId = currentTask.assignedWorkerId;
+  const clarificationId = generateId();
+  const now = Date.now();
+  const clarification: ClarificationRequest = {
+    id: clarificationId,
+    taskId: params.taskId,
+    requestedBy: params.requestedBy,
+    requestedByWorkerId: params.requestedByWorkerId,
+    requestedByRole: params.requestedByRole,
+    question: params.question,
+    questionSchema: params.questionSchema,
+    blockingReason: params.blockingReason,
+    context: params.context,
+    status: "pending",
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  const state = updateTeamState((s) => {
+    s.clarifications[clarificationId] = clarification;
+    const task = s.tasks[params.taskId];
+    if (!task) {
+      return;
+    }
+
+    const assignedWorkerId = task.assignedWorkerId;
+    task.status = "blocked";
+    task.progress = `Awaiting clarification: ${params.question}`;
+    task.clarificationRequestId = clarificationId;
+    task.assignedWorkerId = undefined;
+    task.updatedAt = now;
+
+    if (assignedWorkerId && s.workers[assignedWorkerId]) {
+      const assignedWorker = s.workers[assignedWorkerId];
+      if (assignedWorker.status !== "offline") {
+        assignedWorker.status = "idle";
+      }
+      assignedWorker.currentTaskId = undefined;
+    }
+  });
+
+  await cancelTaskExecution(params.taskId, previousWorkerId, "clarification request", deps);
+
+  const updatedTask = state.tasks[params.taskId];
+  wsServer.broadcastUpdate({ type: "clarification:requested", data: clarification });
+  if (updatedTask) {
+    recordTaskExecutionEvent(params.taskId, {
+      type: "lifecycle",
+      phase: "clarification_requested",
+      source: "controller",
+      message: `Clarification requested: ${params.question}`,
+      role: clarification.requestedByRole,
+      workerId: clarification.requestedByWorkerId,
+    }, deps);
+    wsServer.broadcastUpdate({ type: "task:updated", data: serializeTask(updatedTask) });
+  }
+
+  return { status: "created", clarification, task: updatedTask };
+}
+
 function ensureTaskResultContract(
   taskId: string,
   result: string,
@@ -1602,10 +2935,35 @@ function ensureTaskResultContract(
     return undefined;
   }
   if (currentTask.resultContract) {
+    // Worker submitted a structured contract — but it may be missing preview
+    // fields (artifactType, previewCommand, etc.). Enrich deliverables
+    // so the PreviewManager can auto-launch previews.
+    let enriched = enrichDeliverablesWithPreviewInference(currentTask.resultContract, result);
+    if (!enriched) {
+      // Text-based enrichment failed — scan the workspace filesystem for HTML files.
+      enriched = enrichWithFilesystemHtmlScan(currentTask.resultContract, currentTask.projectDir);
+    }
+    if (enriched) {
+      deps.updateTeamState((teamState) => {
+        const task = teamState.tasks[taskId];
+        if (task) {
+          task.resultContract = enriched;
+          task.updatedAt = Date.now();
+        }
+      });
+      return enriched;
+    }
     return currentTask.resultContract;
   }
 
-  const contract = backfillWorkerTaskResultContract(currentTask, result, error);
+  let contract = backfillWorkerTaskResultContract(currentTask, result, error);
+  if (!error) {
+    const enriched = enrichDeliverablesWithPreviewInference(contract, result)
+      ?? enrichWithFilesystemHtmlScan(contract, currentTask.projectDir);
+    if (enriched) {
+      contract = enriched;
+    }
+  }
   deps.updateTeamState((teamState) => {
     const task = teamState.tasks[taskId];
     if (!task || task.resultContract) {
@@ -1670,9 +3028,78 @@ function buildResultContractSection(task: TaskInfo): string {
   if (contract.notes) {
     lines.push(`Notes: ${contract.notes}`);
   }
+  if (contract.discoveredPatterns && contract.discoveredPatterns.length > 0) {
+    lines.push("Discovered patterns:");
+    for (const pattern of contract.discoveredPatterns) {
+      lines.push(`- ${pattern}`);
+    }
+  }
   return lines.join("\n");
 }
 
+const MAX_PATTERNS_FILE_BYTES = 64 * 1024;
+
+function consolidateDiscoveredPatterns(
+  contract: WorkerTaskResultContract,
+  taskId: string,
+  role: string | undefined,
+  logger: PluginLogger,
+): void {
+  const patterns = contract.discoveredPatterns;
+  if (!patterns || patterns.length === 0) {
+    return;
+  }
+  try {
+    const workspaceDir = resolveTeamClawWorkspaceDir();
+    const patternsFile = path.join(workspaceDir, "memory", "patterns.md");
+    fs.mkdirSync(path.join(workspaceDir, "memory"), { recursive: true });
+
+    let currentSize = 0;
+    try {
+      currentSize = fs.statSync(patternsFile).size;
+    } catch {
+      // File doesn't exist yet; will be created by append.
+    }
+    if (currentSize > MAX_PATTERNS_FILE_BYTES) {
+      logger.info(`Controller: patterns.md already ${currentSize} bytes, skipping consolidation for ${taskId}`);
+      return;
+    }
+
+    const roleLabel = role ?? "unknown";
+    const timestamp = new Date().toISOString().slice(0, 10);
+    const section = [
+      "",
+      `## ${timestamp} — ${taskId} (${roleLabel})`,
+      ...patterns.map((p) => `- ${p}`),
+    ].join("\n") + "\n";
+
+    fs.appendFileSync(patternsFile, section, "utf8");
+    logger.info(`Controller: consolidated ${patterns.length} pattern(s) from ${taskId} into patterns.md`);
+  } catch (err) {
+    logger.warn(`Controller: failed to consolidate patterns for ${taskId}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function buildConsolidatedPatternsContext(): string {
+  try {
+    const workspaceDir = resolveTeamClawWorkspaceDir();
+    const patternsFile = path.join(workspaceDir, "memory", "patterns.md");
+    const content = fs.readFileSync(patternsFile, "utf8").trim();
+    // Only inject if there are actual patterns (more than just the header)
+    const lines = content.split("\n").filter((l: string) => l.startsWith("- "));
+    if (lines.length === 0) {
+      return "";
+    }
+    return [
+      "## Discovered Codebase Patterns",
+      "Previous workers discovered these reusable patterns. Apply them where relevant:",
+      ...lines,
+    ].join("\n");
+  } catch {
+    return "";
+  }
+}
+
 function revertTaskAssignment(taskId: string, workerId: string, deps: ControllerHttpDeps): TaskInfo | undefined {
   const { updateTeamState, wsServer } = deps;
   let revertEvent: TaskExecutionEvent | undefined;
@@ -1702,6 +3129,7 @@ function revertTaskAssignment(taskId: string, workerId: string, deps: Controller
       }
       worker.currentTaskId = undefined;
     }
+
   });
 
   const updatedTask = state.tasks[taskId];
@@ -1723,17 +3151,6 @@ async function deliverMessageToWorker(
   message: TeamMessage,
   deps: ControllerHttpDeps,
 ): Promise<void> {
-  const { localWorkerManager } = deps;
-
-  if (localWorkerManager?.isLocalWorkerId(worker.id)) {
-    const queued = await localWorkerManager.queueMessage(worker.id, message);
-    if (queued) {
-      return;
-    }
-
-    deps.logger.warn(`Controller: local message path unavailable for ${worker.id}, falling back to worker URL`);
-  }
-
   const res = await fetch(`${worker.url}/api/v1/messages`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -1774,14 +3191,21 @@ async function dispatchTaskToWorker(
   worker: WorkerInfo,
   deps: ControllerHttpDeps,
 ): Promise<void> {
-  const { getTeamState, localWorkerManager } = deps;
+  const { getTeamState } = deps;
   const state = getTeamState();
   const task = state?.tasks[taskId];
   if (!task) {
     throw new Error(`task ${taskId} not found`);
   }
 
-  const sharedWorkspace = localWorkerManager?.isLocalWorkerId(worker.id) ?? false;
+  // Ensure project directory exists
+  if (task.projectDir) {
+    const projectPath = path.join(resolveTeamClawProjectsDir(), task.projectDir);
+    try { fs.mkdirSync(projectPath, { recursive: true }); } catch { /* best-effort */ }
+  }
+
+  const sharedWorkspace = deps.workerProvisioningManager?.isSharedWorkspaceWorker(worker.id)
+    || false;
   const repoState = await refreshControllerRepoState(deps);
   const repoInfo = buildRepoSyncInfo(repoState, sharedWorkspace);
   const description = buildTaskAssignmentDescription(task, state ?? null, repoInfo);
@@ -1793,20 +3217,12 @@ async function dispatchTaskToWorker(
     description,
     priority: task.priority,
     recommendedSkills,
+    projectDir: task.projectDir,
     executionSessionKey: executionIdentity.executionSessionKey,
     executionIdempotencyKey: executionIdentity.executionIdempotencyKey,
     repo: repoInfo,
   };
 
-  if (localWorkerManager?.isLocalWorkerId(worker.id)) {
-    const accepted = await localWorkerManager.dispatchTask(worker.id, assignment);
-    if (accepted) {
-      return;
-    }
-
-    deps.logger.warn(`Controller: local dispatch path unavailable for ${worker.id}, falling back to worker URL`);
-  }
-
   const res = await fetch(`${worker.url}/api/v1/tasks/assign`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -1903,12 +3319,21 @@ async function autoAssignPendingTasks(
       break;
     }
 
-    const nextAssignment = taskRouter
+    const candidateAssignments = taskRouter
       .autoAssignPendingTasks(state.tasks, state.workers)
-      .filter(({ worker }) => !preferredWorkerId || worker.id === preferredWorkerId)
-      .find(({ task, worker }) => !attemptedPairs.has(`${task.id}:${worker.id}`));
+      .filter(({ task, worker }) => !attemptedPairs.has(`${task.id}:${worker.id}`));
+
+    const nextAssignment = (
+      (preferredWorkerId
+        ? candidateAssignments.find(({ worker }) => worker.id === preferredWorkerId)
+        : undefined)
+      ?? candidateAssignments[0]
+    );
 
     if (!nextAssignment) {
+      scheduleProvisioningReconcile(deps, preferredWorkerId
+        ? `auto-assign-wait:${preferredWorkerId}`
+        : "auto-assign-wait");
       break;
     }
 
@@ -1964,6 +3389,19 @@ export function createControllerHttpServer(deps: ControllerHttpDeps): http.Serve
   // Attach WebSocket
   wsServer.attach(server);
 
+  setTimeout(() => {
+    const state = deps.getTeamState();
+    const pendingCount = state
+      ? Object.values(state.tasks).filter((t) => t.status === "pending" && !t.assignedWorkerId).length
+      : 0;
+    if (pendingCount > 0) {
+      logger.info(`Controller: startup reconciliation — ${pendingCount} pending tasks, triggering auto-assign`);
+      void autoAssignPendingTasks(deps).catch((err) => {
+        logger.warn(`Controller: startup auto-assign failed: ${String(err)}`);
+      });
+    }
+  }, 2000);
+
   return server;
 }
 
@@ -1975,6 +3413,7 @@ async function handleRequest(
 ): Promise<void> {
   const { config, logger, getTeamState, updateTeamState, taskRouter, messageRouter, wsServer } = deps;
   const requestUrl = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+  const currentState = getTeamState();
 
   // ==================== Web UI ====================
   if (req.method === "GET" && pathname === "/") {
@@ -1997,6 +3436,12 @@ async function handleRequest(
       serveStaticFile(res, path.join(uiPath, file), "text/css; charset=utf-8");
     } else if (file.endsWith(".js")) {
       serveStaticFile(res, path.join(uiPath, file), "application/javascript; charset=utf-8");
+    } else if (file.endsWith(".png")) {
+      serveStaticFile(res, path.join(uiPath, file), "image/png");
+    } else if (file.endsWith(".svg")) {
+      serveStaticFile(res, path.join(uiPath, file), "image/svg+xml; charset=utf-8");
+    } else if (file.endsWith(".ico")) {
+      serveStaticFile(res, path.join(uiPath, file), "image/x-icon");
     } else {
       serveStaticFile(res, path.join(uiPath, file), "application/octet-stream");
     }
@@ -2007,7 +3452,24 @@ async function handleRequest(
 
   if (req.method === "GET" && pathname === "/api/v1/workspace/tree") {
     try {
-      sendJson(res, 200, await listWorkspaceTree());
+      // depth=N limits tree expansion (default 1 for lazy loading)
+      const depthParam = requestUrl.searchParams.get("depth");
+      const maxDepth = depthParam !== null ? Math.max(0, Math.min(parseInt(depthParam, 10) || 1, 8)) : 1;
+      sendJson(res, 200, await listWorkspaceTree(maxDepth));
+    } catch (err) {
+      sendError(res, workspaceRequestErrorStatus(err), workspaceRequestErrorMessage(err));
+    }
+    return;
+  }
+
+  if (req.method === "GET" && pathname === "/api/v1/workspace/subtree") {
+    const dirPath = requestUrl.searchParams.get("path") ?? "";
+    if (!dirPath) {
+      sendError(res, 400, "path is required");
+      return;
+    }
+    try {
+      sendJson(res, 200, { entries: await listWorkspaceSubtree(dirPath) });
     } catch (err) {
       sendError(res, workspaceRequestErrorStatus(err), workspaceRequestErrorMessage(err));
     }
@@ -2102,11 +3564,6 @@ async function handleRequest(
   // DELETE /api/v1/workers/:id
   if (req.method === "DELETE" && pathname.match(/^\/api\/v1\/workers\/[^/]+$/)) {
     const workerId = pathname.split("/").pop()!;
-    if (deps.localWorkerManager?.isLocalWorkerId(workerId)) {
-      sendError(res, 400, "Local workers are managed by controller config");
-      return;
-    }
-
     if (deps.workerProvisioningManager?.hasManagedWorker(workerId)) {
       await deps.workerProvisioningManager.onWorkerRemoved(workerId, "worker delete requested");
     }
@@ -2203,6 +3660,13 @@ async function handleRequest(
       sendError(res, 400, "title is required");
       return;
     }
+    if (createdBy === "controller") {
+      const readinessGate = shouldBlockControllerUntilProvisioningReady(deps, currentState);
+      if (readinessGate.blocked && readinessGate.readiness) {
+        sendError(res, 503, buildStartupReadinessMessage(readinessGate.readiness));
+        return;
+      }
+    }
     if (createdBy === "controller" && shouldBlockControllerWithoutWorkers(deps.config, getTeamState())) {
       sendError(res, 409, buildControllerNoWorkersMessage());
       return;
@@ -2212,6 +3676,17 @@ async function handleRequest(
     const now = Date.now();
     const repoState = await refreshControllerRepoState(deps);
 
+    // Resolve project directory: inherit from parent run, or generate from title
+    let projectDir: string | undefined;
+    if (controllerSessionKey) {
+      const runId = findLatestControllerRunIdForSession(controllerSessionKey, getTeamState(), { preferActive: true });
+      const parentRun = runId ? getTeamState()?.controllerRuns[runId] : undefined;
+      projectDir = parentRun?.projectDir;
+    }
+    if (!projectDir) {
+      projectDir = deriveProjectSlug(title);
+    }
+
     const task: TaskInfo = {
       id: taskId,
       title,
@@ -2222,6 +3697,7 @@ async function handleRequest(
       createdBy,
       recommendedSkills: recommendedSkills.length > 0 ? recommendedSkills : undefined,
       controllerSessionKey,
+      projectDir,
       createdAt: now,
       updatedAt: now,
     };
@@ -2536,8 +4012,18 @@ async function handleRequest(
       if (!task) {
         return;
       }
-      task.resultContract = contract;
+      task.resultContract = filterStaleDeliverables(contract, task.projectDir);
       task.updatedAt = Date.now();
+      // Enrich deliverables with preview inference so PreviewManager can auto-launch.
+      // Workers typically don't include artifactType/previewCommand in their contracts.
+      const existingResult = task.result ?? "";
+      let enriched = enrichDeliverablesWithPreviewInference(task.resultContract, existingResult);
+      if (!enriched) {
+        enriched = enrichWithFilesystemHtmlScan(contract, task.projectDir);
+      }
+      if (enriched) {
+        task.resultContract = enriched;
+      }
     });
     recordTaskExecutionEvent(taskId, {
       type: "output",
@@ -2548,6 +4034,7 @@ async function handleRequest(
       workerId,
       role: currentTask.assignedRole,
     }, deps);
+    consolidateDiscoveredPatterns(contract, taskId, currentTask.assignedRole, logger);
     sendJson(res, 201, { task: serializeTask(state.tasks[taskId]) });
     return;
   }
@@ -2557,7 +4044,7 @@ async function handleRequest(
     const taskId = pathname.split("/")[4]!;
     const body = await parseJsonBody(req);
     const result = typeof body.result === "string" ? body.result : "";
-    const error = typeof body.error === "string" ? body.error : undefined;
+    let error = typeof body.error === "string" ? body.error : undefined;
     const workerId = typeof body.workerId === "string" ? body.workerId : undefined;
     const currentTask = getTeamState()?.tasks[taskId];
     if (!currentTask) {
@@ -2585,14 +4072,72 @@ async function handleRequest(
         phase: "result_contract_recorded",
         source: "worker",
         status: error ? "failed" : "running",
-        message: submittedContract.summary,
+          message: submittedContract.summary,
+          workerId,
+          role: currentTask.assignedRole,
+        }, deps);
+    }
+
+    if (!error && submittedContract?.outcome === "blocked") {
+      const requested = await requestTaskClarification({
+        taskId,
+        requestedBy: workerId ?? "worker",
+        requestedByWorkerId: workerId,
+        requestedByRole: currentTask.assignedRole,
+        question: submittedContract.questions[0]
+          ?? "This task is blocked and needs a human decision before work can continue. What should TeamClaw do next?",
+        blockingReason: submittedContract.blockers[0] ?? submittedContract.summary,
+        context: [
+          submittedContract.notes,
+          result.trim(),
+          submittedContract.keyPoints.length > 0
+            ? `Worker-provided commands/details:\n${submittedContract.keyPoints.join("\n")}`
+            : "",
+        ].filter(Boolean).join("\n\n"),
+      }, deps);
+      if (requested.status === "missing-task") {
+        sendError(res, 404, "Task not found");
+        return;
+      }
+      if (requested.status === "conflict") {
+        sendError(res, 409, "Cannot request clarification for a completed task");
+        return;
+      }
+      sendJson(res, requested.status === "already-pending" ? 200 : 201, {
+        status: requested.status,
+        clarification: requested.clarification,
+        task: serializeTask(requested.task),
+      });
+      return;
+    }
+
+    const gatedTask = getTeamState()?.tasks[taskId];
+    if (
+      !error
+      && gatedTask
+      && taskRequiresMeaningfulProjectChangeGate(gatedTask)
+      && !projectHasMeaningfulFileChanges(gatedTask)
+      && !allowsNoChangeCompletion(gatedTask, submittedContract, result)
+    ) {
+      error = "Task reported completion but no meaningful project file changes were detected in the assigned project directory.";
+      recordTaskExecutionEvent(taskId, {
+        type: "warning",
+        phase: "completion_gate",
+        source: "controller",
+        status: "failed",
+        message: error,
         workerId,
-        role: currentTask.assignedRole,
+        role: gatedTask.assignedRole,
       }, deps);
     }
 
     const updatedTask = applyTaskResult(taskId, result, error, deps);
     ensureTaskResultContract(taskId, result, error, deps);
+    if (!error) {
+      deps.previewManager?.syncTaskPreviews(taskId).catch((err) => {
+        logger.warn(`Controller: failed to sync previews for ${taskId}: ${String(err)}`);
+      });
+    }
     if (!workerId || workerId !== previousWorkerId) {
       await cancelTaskExecution(taskId, previousWorkerId, "manual result submission", deps);
     }
@@ -2644,6 +4189,14 @@ async function handleRequest(
       return;
     }
 
+    // When a result contract is backfilled, the task is effectively complete —
+    // trigger preview sync so that any web-app deliverables get previewed.
+    if (recorded.event?.phase === "result_contract_backfilled") {
+      deps.previewManager?.syncTaskPreviews(taskId).catch((err) => {
+        logger.warn(`Controller: failed to sync previews for ${taskId}: ${String(err)}`);
+      });
+    }
+
     sendJson(res, 201, {
       task: serializeTask(recorded.task),
       execution: buildTaskExecutionSummary(recorded.task.execution),
@@ -2674,6 +4227,19 @@ async function handleRequest(
 
     const updatedRun = updateControllerRun(runId, deps, (run) => {
       run.manifest = manifest;
+
+      if (run.projectDir) {
+        const state = deps.getTeamState();
+        if (state) {
+          for (const taskId of run.createdTaskIds) {
+            const task = state.tasks[taskId];
+            if (task && !task.projectDir) {
+              task.projectDir = run.projectDir;
+            }
+          }
+        }
+      }
+
       appendControllerRunEvent(run, {
         type: "output",
         phase: "manifest_recorded",
@@ -2689,6 +4255,18 @@ async function handleRequest(
       return;
     }
 
+    if (manifest.requirementFullyComplete) {
+      logger.info(`Controller: requirement fully complete for session ${sessionKey} (run ${runId})`);
+      wsServer.broadcastUpdate({
+        type: "requirement:complete",
+        data: {
+          runId,
+          sessionKey,
+          requirementSummary: manifest.requirementSummary,
+        },
+      });
+    }
+
     sendJson(res, 201, {
       controllerRun: serializeControllerRun(updatedRun),
       manifest,
@@ -2698,7 +4276,7 @@ async function handleRequest(
 
   // GET /api/v1/controller/runs
   if (req.method === "GET" && pathname === "/api/v1/controller/runs") {
-    const state = getTeamState();
+    const state = reconcileControllerClarifications(deps);
     const controllerRuns = state
       ? Object.values(state.controllerRuns)
         .sort((left, right) => right.updatedAt - left.updatedAt)
@@ -2710,6 +4288,11 @@ async function handleRequest(
 
   // POST /api/v1/controller/intake
   if (req.method === "POST" && pathname === "/api/v1/controller/intake") {
+    const readinessGate = shouldBlockControllerUntilProvisioningReady(deps, currentState);
+    if (readinessGate.blocked && readinessGate.readiness) {
+      sendError(res, 503, buildStartupReadinessMessage(readinessGate.readiness));
+      return;
+    }
     const body = await parseJsonBody(req);
     const message = typeof body.message === "string" ? body.message.trim() : "";
     if (!message) {
@@ -2858,95 +4441,49 @@ async function handleRequest(
     const question = typeof body.question === "string" ? body.question.trim() : "";
     const blockingReason = typeof body.blockingReason === "string" ? body.blockingReason.trim() : "";
     const context = typeof body.context === "string" && body.context.trim() ? body.context.trim() : undefined;
+    const questionSchema = normalizeClarificationQuestionSchema(body.questionSchema);
 
     if (!taskId || !question || !blockingReason) {
       sendError(res, 400, "taskId, question, and blockingReason are required");
       return;
     }
 
-    const currentState = getTeamState();
-    const currentTask = currentState?.tasks[taskId];
-    if (!currentTask) {
-      sendError(res, 404, "Task not found");
-      return;
-    }
-
-    if (currentTask.clarificationRequestId) {
-      const existing = currentState?.clarifications[currentTask.clarificationRequestId];
-      if (existing?.status === "pending") {
-        sendJson(res, 200, { clarification: existing, task: currentTask, status: "already-pending" });
-        return;
-      }
-    }
-
-    if (currentTask.status === "completed" || currentTask.status === "failed") {
-      sendError(res, 409, "Cannot request clarification for a completed task");
-      return;
-    }
-
-    const previousWorkerId = currentTask.assignedWorkerId;
-
-    const clarificationId = generateId();
-    const now = Date.now();
-    const clarification: ClarificationRequest = {
-      id: clarificationId,
+    const requested = await requestTaskClarification({
       taskId,
       requestedBy,
       requestedByWorkerId,
       requestedByRole,
       question,
+      questionSchema,
       blockingReason,
       context,
-      status: "pending",
-      createdAt: now,
-      updatedAt: now,
-    };
-
-    const state = updateTeamState((s) => {
-      s.clarifications[clarificationId] = clarification;
-      const task = s.tasks[taskId];
-      if (!task) {
-        return;
-      }
-
-      const assignedWorkerId = task.assignedWorkerId;
-      task.status = "blocked";
-      task.progress = `Awaiting clarification: ${question}`;
-      task.clarificationRequestId = clarificationId;
-      task.assignedWorkerId = undefined;
-      task.updatedAt = now;
-
-      if (assignedWorkerId && s.workers[assignedWorkerId]) {
-        const assignedWorker = s.workers[assignedWorkerId];
-        if (assignedWorker.status !== "offline") {
-          assignedWorker.status = "idle";
-        }
-        assignedWorker.currentTaskId = undefined;
-      }
-    });
-
-    await cancelTaskExecution(taskId, previousWorkerId, "clarification request", deps);
-
-    const updatedTask = state.tasks[taskId];
-    wsServer.broadcastUpdate({ type: "clarification:requested", data: clarification });
-    if (updatedTask) {
-      recordTaskExecutionEvent(taskId, {
-        type: "lifecycle",
-        phase: "clarification_requested",
-        source: "controller",
-        message: `Clarification requested: ${question}`,
-        role: clarification.requestedByRole,
-        workerId: clarification.requestedByWorkerId,
-      }, deps);
-      wsServer.broadcastUpdate({ type: "task:updated", data: serializeTask(updatedTask) });
+    }, deps);
+    if (requested.status === "missing-task") {
+      sendError(res, 404, "Task not found");
+      return;
+    }
+    if (requested.status === "conflict") {
+      sendError(res, 409, "Cannot request clarification for a completed task");
+      return;
+    }
+    if (requested.status === "already-pending") {
+      sendJson(res, 200, {
+        clarification: requested.clarification,
+        task: serializeTask(requested.task),
+        status: "already-pending",
+      });
+      return;
     }
-    sendJson(res, 201, { clarification, task: serializeTask(updatedTask) });
+    sendJson(res, 201, {
+      clarification: requested.clarification,
+      task: serializeTask(requested.task),
+    });
     return;
   }
 
   // GET /api/v1/clarifications
   if (req.method === "GET" && pathname === "/api/v1/clarifications") {
-    const state = getTeamState();
+    const state = reconcileControllerClarifications(deps);
     const clarifications = state
       ? Object.values(state.clarifications).sort((left, right) => right.createdAt - left.createdAt)
       : [];
@@ -2961,16 +4498,20 @@ async function handleRequest(
   if (req.method === "POST" && pathname.match(/^\/api\/v1\/clarifications\/[^/]+\/answer$/)) {
     const clarificationId = pathname.split("/")[4]!;
     const body = await parseJsonBody(req);
-    const answer = typeof body.answer === "string" ? body.answer.trim() : "";
+    const answerValue = typeof body.answerValue === "string" ? body.answerValue.trim() : undefined;
+    const answerValues = Array.isArray(body.answerValues)
+      ? body.answerValues.map((entry) => String(entry || "").trim()).filter(Boolean)
+      : undefined;
+    const answerNumber = typeof body.answerNumber === "number" && Number.isFinite(body.answerNumber)
+      ? body.answerNumber
+      : undefined;
+    const answerComment = typeof body.answerComment === "string" && body.answerComment.trim()
+      ? body.answerComment.trim()
+      : undefined;
     const answeredBy = typeof body.answeredBy === "string" && body.answeredBy.trim()
       ? body.answeredBy.trim()
       : "human";
 
-    if (!answer) {
-      sendError(res, 400, "answer is required");
-      return;
-    }
-
     const currentState = getTeamState();
     const currentClarification = currentState?.clarifications[clarificationId];
     if (!currentClarification) {
@@ -2978,6 +4519,19 @@ async function handleRequest(
       return;
     }
 
+    const answer = buildStructuredClarificationAnswer(currentClarification, {
+      answer: typeof body.answer === "string" ? body.answer.trim() : "",
+      answerValue,
+      answerValues,
+      answerNumber,
+      answerComment,
+    });
+
+    if (!answer) {
+      sendError(res, 400, "answer is required");
+      return;
+    }
+
     if (currentClarification.status === "answered") {
       sendError(res, 409, "Clarification request already answered");
       return;
@@ -2992,6 +4546,10 @@ async function handleRequest(
 
       clarification.status = "answered";
       clarification.answer = answer;
+      clarification.answerValue = answerValue;
+      clarification.answerValues = answerValues;
+      clarification.answerNumber = answerNumber;
+      clarification.answerComment = answerComment;
       clarification.answeredBy = answeredBy;
       clarification.answeredAt = now;
       clarification.updatedAt = now;
@@ -3009,7 +4567,7 @@ async function handleRequest(
     });
 
     const clarification = state.clarifications[clarificationId];
-    const task = clarification ? state.tasks[clarification.taskId] : undefined;
+    const task = clarification?.taskId ? state.tasks[clarification.taskId] : undefined;
 
     let responseMessage: TeamMessage | undefined;
     if (clarification?.requestedByRole && task) {
@@ -3043,6 +4601,13 @@ async function handleRequest(
 
     let resumedTask = task;
     let resumedWorker: WorkerInfo | null = null;
+    let continuedControllerRun: {
+      sessionKey: string;
+      controllerRunId?: string;
+      runId?: string;
+      reply?: string;
+      queued?: boolean;
+    } | null = null;
     if (task) {
       const latestState = getTeamState()!;
       if (clarification?.requestedByWorkerId && latestState.workers[clarification.requestedByWorkerId]?.status === "idle") {
@@ -3056,6 +4621,25 @@ async function handleRequest(
           assignedRole: task.assignedRole,
         });
       }
+    } else if (clarification?.controllerRunId) {
+      const targetSessionKey = clarification.controllerSessionKey
+        || state.controllerRuns[clarification.controllerRunId]?.sessionKey;
+      if (targetSessionKey) {
+        continuedControllerRun = {
+          sessionKey: targetSessionKey,
+          controllerRunId: clarification.controllerRunId,
+          queued: true,
+        };
+        void runControllerIntake(
+          buildControllerClarificationAnswerMessage(clarification, answer, answeredBy),
+          targetSessionKey,
+          deps,
+        ).catch((err) => {
+          deps.logger.warn(
+            `Controller: failed to continue intake after clarification ${clarification.id}: ${String(err)}`,
+          );
+        });
+      }
     }
 
     wsServer.broadcastUpdate({ type: "clarification:answered", data: clarification });
@@ -3075,6 +4659,7 @@ async function handleRequest(
       clarification,
       task: serializeTask(resumedTask),
       resumedWorker,
+      controllerRun: continuedControllerRun,
       message: responseMessage,
     });
     return;
@@ -3180,7 +4765,10 @@ async function handleRequest(
 
   // GET /api/v1/team/status
   if (req.method === "GET" && pathname === "/api/v1/team/status") {
-    const state = getTeamState();
+    const state = reconcileControllerClarifications(deps);
+    const startupReadiness = getEffectiveStartupReadiness(deps, state);
+    const modelReadiness = getTeamClawModelReadiness();
+    const externalWorkerInstall = buildExternalWorkerInstallInfo(req, config);
     if (!state) {
       sendJson(res, 200, {
         teamName: config.teamName,
@@ -3189,8 +4777,12 @@ async function handleRequest(
         controllerRuns: [],
         messages: [],
         clarifications: [],
+        previews: [],
         repo: null,
         pendingClarificationCount: 0,
+        modelReadiness,
+        externalWorkerInstall,
+        provisioning: startupReadiness ? { startupReadiness } : undefined,
       });
       return;
     }
@@ -3205,7 +4797,14 @@ async function handleRequest(
         .map((run) => serializeControllerRun(run)),
       messages: state.messages,
       clarifications,
+      previews: Object.values(state.previews ?? {}),
       repo: state.repo ?? null,
+      modelReadiness,
+      externalWorkerInstall,
+      provisioning: {
+        ...(state.provisioning ?? { workers: {} }),
+        startupReadiness,
+      },
       taskCount: Object.keys(state.tasks).length,
       workerCount: Object.keys(state.workers).length,
       pendingClarificationCount: clarifications.filter((item) => item.status === "pending").length,
@@ -3219,9 +4818,145 @@ async function handleRequest(
     return;
   }
 
+  // /api/v1/previews/:id/* — proxy to preview subprocess
+  if (req.method === "GET" || req.method === "HEAD" || req.method === "POST" || req.method === "PUT" || req.method === "DELETE") {
+    const previewPrefix = "/api/v1/previews/";
+    if (pathname.startsWith(previewPrefix)) {
+      const remaining = pathname.slice(previewPrefix.length);
+      const slashIdx = remaining.indexOf("/");
+      const previewId = slashIdx >= 0 ? remaining.slice(0, slashIdx) : remaining;
+      const subPath = slashIdx >= 0 ? remaining.slice(slashIdx) : "/";
+
+      const state = deps.getTeamState();
+      const preview = state?.previews?.[previewId];
+      if (!preview || preview.status !== "healthy") {
+        const status = preview?.status ?? "unknown";
+        const errMsg = preview?.lastError;
+        sendJson(res, 503, { error: "Preview not available", previewId, status, lastError: errMsg ?? undefined });
+        return;
+      }
+
+      const proxyPathPrefix = `/api/v1/previews/${encodeURIComponent(previewId)}`;
+      const proxyReq = http.request(
+        {
+          hostname: "127.0.0.1",
+          port: preview.targetPort,
+          path: subPath + (requestUrl.search || ""),
+          method: req.method,
+          headers: {
+            ...req.headers,
+            host: `127.0.0.1:${preview.targetPort}`,
+            "accept-encoding": "identity",
+            "x-forwarded-for": req.socket.remoteAddress ?? "",
+            "x-forwarded-host": req.headers.host ?? "",
+            "x-forwarded-proto": "http",
+          },
+        },
+        (proxyRes: http.IncomingMessage) => {
+          const contentType = (proxyRes.headers["content-type"] ?? "").toLowerCase();
+          if (proxyRes.statusCode !== 200 && proxyRes.statusCode !== 201 && proxyRes.statusCode !== 301 && proxyRes.statusCode !== 302 && proxyRes.statusCode !== 304) {
+            res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+            proxyRes.pipe(res);
+            return;
+          }
+
+          if (contentType.includes("text/html")) {
+            const chunks: Buffer[] = [];
+            proxyRes.on("data", (chunk: Buffer) => chunks.push(chunk));
+            proxyRes.on("end", () => {
+              let raw = Buffer.concat(chunks);
+              // Decompress if the upstream response is compressed (brotli/gzip/deflate).
+              const encoding = (proxyRes.headers["content-encoding"] ?? "").toLowerCase();
+              try {
+                if (encoding === "br") {
+                  raw = zlib.brotliDecompressSync(raw);
+                } else if (encoding === "gzip") {
+                  raw = zlib.gunzipSync(raw);
+                } else if (encoding === "deflate") {
+                  raw = zlib.inflateSync(raw);
+                }
+              } catch {
+                // If decompression fails, use raw bytes as-is.
+              }
+              const body = raw.toString("utf-8");
+              // Rewrite absolute-path references (href="/...", src="/...", action="/...")
+              // to include the proxy prefix so all navigation stays within the proxy.
+              const rewritten = body.replace(
+                /\b(href|src|action)\s*=\s*"\/([^"]*)"/g,
+                `$1="${proxyPathPrefix}/$2"`,
+              ).replace(
+                /\b(href|src|action)\s*=\s*'\/([^']*)'/g,
+                `$1='${proxyPathPrefix}/$2'`,
+              );
+              const resHeaders = { ...proxyRes.headers };
+              // We've decoded and rewritten the body — remove upstream encoding headers.
+              delete resHeaders["content-encoding"];
+              delete resHeaders["transfer-encoding"];
+              resHeaders["content-length"] = String(Buffer.byteLength(rewritten, "utf-8"));
+              res.writeHead(proxyRes.statusCode ?? 200, resHeaders);
+              res.end(rewritten);
+            });
+          } else {
+            res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+            proxyRes.pipe(res);
+          }
+        },
+      );
+      proxyReq.on("error", (err: Error) => {
+        deps.logger.warn(`Controller: preview proxy error for ${previewId}: ${String(err)}`);
+        if (!res.headersSent) {
+          sendJson(res, 502, { error: "Preview proxy error", previewId, message: String(err) });
+        }
+      });
+      req.pipe(proxyReq);
+      return;
+    }
+  }
+
+  // GET /api/v1/reports — list all delivery reports
+  if (req.method === "GET" && pathname === "/api/v1/reports") {
+    const state = deps.getTeamState();
+    const reports = Object.values(state?.reports ?? {}).sort((a, b) => b.generatedAt - a.generatedAt);
+    sendJson(res, 200, { reports });
+    return;
+  }
+
+  // GET /api/v1/reports/:sessionKey — serve delivery report page
+  if (req.method === "GET" && pathname.startsWith("/api/v1/reports/")) {
+    const sessionKey = decodeURIComponent(pathname.slice("/api/v1/reports/".length));
+    const state = deps.getTeamState();
+    if (!state) {
+      sendError(res, 503, "Team state not loaded");
+      return;
+    }
+    const report = generateDeliveryReport(sessionKey, state, normalizeControllerIntakeSessionKey);
+    if (!report) {
+      sendError(res, 404, "No report found for this session");
+      return;
+    }
+    const accept = (req.headers["accept"] ?? "").toLowerCase();
+    if (accept.includes("application/json")) {
+      sendJson(res, 200, { report });
+    } else {
+      const html = renderReportHtml(report);
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Content-Length": Buffer.byteLength(html, "utf-8") });
+      res.end(html);
+    }
+    return;
+  }
+
   // GET /api/v1/health
   if (req.method === "GET" && pathname === "/api/v1/health") {
-    sendJson(res, 200, { status: "ok", mode: "controller", timestamp: Date.now() });
+    const readiness = getEffectiveStartupReadiness(deps, currentState);
+    const modelReadiness = getTeamClawModelReadiness();
+    const statusCode = readiness && readiness.status !== "ready" ? 503 : 200;
+    sendJson(res, statusCode, {
+      status: readiness?.status === "degraded" ? "degraded" : readiness?.status === "checking" ? "starting" : "ok",
+      mode: "controller",
+      timestamp: Date.now(),
+      provisioningReadiness: readiness,
+      modelReadiness,
+    });
     return;
   }