@teamclaws/teamclaw 2026.3.26-2 → 2026.4.2-1

package/src/discovery.ts

@@ -66,7 +66,7 @@ export class MDnsBrowser {
 
         browser.on("up", (service) => {
           const txtRecord = service.txt as Record<string, string> | undefined;
-          const svcTeamName = txtRecord?.teamName ?? "default";
+          const svcTeamName = txtRecord?.teamName ?? "TeamClaw";
           const host = Array.isArray(service.addresses) && service.addresses.length > 0
             ? service.addresses[0]
             : (service.host ?? "localhost");

package/src/git-collaboration.ts

@@ -4,9 +4,11 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import type { PluginLogger } from "../api.js";
 import type { GitRepoState, PluginConfig, RepoSyncInfo } from "./types.js";
-import { resolveDefaultOpenClawWorkspaceDir } from "./openclaw-workspace.js";
+import { resolveTeamClawWorkspaceDir } from "./openclaw-workspace.js";
 
 const TEAMCLAW_IMPORT_REF_PREFIX = "refs/teamclaw/imports";
+const BUNDLE_IMPORT_MAX_RETRIES = 3;
+const BUNDLE_IMPORT_RETRY_DELAY_MS = 2_000;
 const TEAMCLAW_RUNTIME_EXCLUDES = [
   ".openclaw/",
   ".clawhub/",
@@ -51,7 +53,7 @@ export async function ensureControllerGitRepo(
   config: PluginConfig,
   logger: PluginLogger,
 ): Promise<GitRepoState | null> {
-  const workspaceDir = resolveDefaultOpenClawWorkspaceDir();
+  const workspaceDir = resolveTeamClawWorkspaceDir();
   return await withRepoLock(workspaceDir, async () => ensureControllerGitRepoUnlocked(config, logger, workspaceDir));
 }
 
@@ -135,7 +137,7 @@ export async function exportControllerGitBundle(
   config: PluginConfig,
   logger: PluginLogger,
 ): Promise<{ repo: GitRepoState; data: Buffer; filename: string }> {
-  const workspaceDir = resolveDefaultOpenClawWorkspaceDir();
+  const workspaceDir = resolveTeamClawWorkspaceDir();
   return await withRepoLock(workspaceDir, async () => {
     const repo = await ensureControllerGitRepoUnlocked(config, logger, workspaceDir);
     if (!repo?.enabled) {
@@ -170,7 +172,7 @@ export async function importControllerGitBundle(
     workerId?: string;
   } = {},
 ): Promise<RepoImportResult> {
-  const workspaceDir = resolveDefaultOpenClawWorkspaceDir();
+  const workspaceDir = resolveTeamClawWorkspaceDir();
   return await withRepoLock(workspaceDir, async () => {
     const repo = await ensureControllerGitRepoUnlocked(config, logger, workspaceDir);
     if (!repo?.enabled) {
@@ -178,14 +180,21 @@ export async function importControllerGitBundle(
     }
 
     const refreshedBeforeImport = await readGitRepoState(config, repo.remoteReady);
+    let hadStashed = false;
     if (refreshedBeforeImport.dirty) {
-      return {
-        merged: false,
-        fastForwarded: false,
-        alreadyUpToDate: false,
-        repo: refreshedBeforeImport,
-        message: "Controller workspace has uncommitted changes; refusing bundle import until the shared repo is clean.",
-      };
+      logger.info("Controller workspace has uncommitted changes; stashing before bundle import");
+      const stashResult = await tryGit(["stash", "--include-untracked"], { cwd: workspaceDir });
+      if (stashResult.exitCode === 0) {
+        hadStashed = true;
+      } else {
+        return {
+          merged: false,
+          fastForwarded: false,
+          alreadyUpToDate: false,
+          repo: refreshedBeforeImport,
+          message: "Controller workspace has uncommitted changes that cannot be stashed; refusing bundle import.",
+        };
+      }
     }
 
     const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "teamclaw-import-"));
@@ -215,15 +224,21 @@ export async function importControllerGitBundle(
         fastForwarded = false;
         const mergeResult = await tryGit(["merge", "--no-edit", importRef], { cwd: workspaceDir });
         if (mergeResult.exitCode !== 0) {
+          // Both ff-only and regular merge failed — worker history diverged from controller.
+          // Fall back to "theirs" strategy to preserve worker changes (the agent just finished work).
           await abortMergeIfNeeded(workspaceDir);
-          const currentRepo = await readGitRepoState(config, repo.remoteReady);
-          return {
-            merged: false,
-            fastForwarded: false,
-            alreadyUpToDate: false,
-            repo: currentRepo,
-            message: `Failed to merge worker bundle for task ${meta.taskId ?? "unknown"}: ${formatCommandError("git merge", mergeResult)}`,
-          };
+          const theirsResult = await tryGit(["merge", "--no-edit", "-X", "theirs", importRef], { cwd: workspaceDir });
+          if (theirsResult.exitCode !== 0) {
+            await abortMergeIfNeeded(workspaceDir);
+            const currentRepo = await readGitRepoState(config, repo.remoteReady);
+            return {
+              merged: false,
+              fastForwarded: false,
+              alreadyUpToDate: false,
+              repo: currentRepo,
+              message: `Failed to merge worker bundle for task ${meta.taskId ?? "unknown"} even with theirs strategy: ${formatCommandError("git merge", theirsResult)}`,
+            };
+          }
         }
       }
 
@@ -238,6 +253,12 @@ export async function importControllerGitBundle(
           : `Imported worker bundle from ${meta.workerId ?? "worker"} with a merge commit.`,
       };
     } finally {
+      if (hadStashed) {
+        const popResult = await tryGit(["stash", "pop"], { cwd: workspaceDir });
+        if (popResult.exitCode !== 0) {
+          logger.warn(`Failed to restore stashed changes after bundle import: ${popResult.stderr?.trim() || "unknown error"}`);
+        }
+      }
       await tryGit(["update-ref", "-d", importRef], { cwd: workspaceDir });
       await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {
         // best-effort temp cleanup
@@ -252,7 +273,7 @@ export async function syncWorkerRepo(
   controllerUrl: string,
   repoInfo: RepoSyncInfo,
 ): Promise<RepoSyncResult> {
-  const workspaceDir = resolveDefaultOpenClawWorkspaceDir();
+  const workspaceDir = resolveTeamClawWorkspaceDir();
   return await withRepoLock(workspaceDir, async () => syncWorkerRepoUnlocked(config, logger, controllerUrl, repoInfo, workspaceDir));
 }
 
@@ -285,7 +306,23 @@ async function syncWorkerRepoUnlocked(
 
   const localRepo = await readGitRepoState(config, false);
   if (localRepo.dirty) {
-    throw new Error("Worker workspace has uncommitted changes; refusing repo sync until the checkout is clean");
+    // Auto-commit leftover changes (e.g. from a prior failed task) instead of
+    // blocking sync.  This mirrors publishWorkerRepoUnlocked's auto-commit and
+    // the controller's stash logic in importControllerGitBundle.
+    logger.info("Worker workspace has uncommitted changes; auto-committing before sync");
+    await runGit(["add", "-A"], { cwd: workspaceDir });
+    const commitResult = await tryGit(
+      ["commit", "-m", "chore(teamclaw): auto-commit uncommitted changes before sync"],
+      { cwd: workspaceDir },
+    );
+    if (commitResult.exitCode !== 0) {
+      // Commit can fail on a repo with no HEAD yet — fall back to stash
+      const stashResult = await tryGit(["stash", "--include-untracked"], { cwd: workspaceDir });
+      if (stashResult.exitCode !== 0) {
+        throw new Error("Worker workspace has uncommitted changes that cannot be committed or stashed");
+      }
+      logger.info("Stashed uncommitted changes (no HEAD commit yet)");
+    }
   }
 
   if (repoInfo.mode === "remote") {
@@ -300,7 +337,17 @@ async function syncWorkerRepoUnlocked(
     await checkoutTrackingBranch(workspaceDir, repoInfo.defaultBranch, `refs/remotes/origin/${repoInfo.defaultBranch}`);
     const mergeResult = await tryGit(["merge", "--ff-only", `refs/remotes/origin/${repoInfo.defaultBranch}`], { cwd: workspaceDir });
     if (mergeResult.exitCode !== 0) {
-      throw new Error(`Failed to fast-forward worker checkout from origin/${repoInfo.defaultBranch}: ${formatCommandError("git merge", mergeResult)}`);
+      // Worker has local commits that diverge from origin — fall back to merge.
+      const regularMerge = await tryGit(["merge", "--no-edit", `refs/remotes/origin/${repoInfo.defaultBranch}`], { cwd: workspaceDir });
+      if (regularMerge.exitCode !== 0) {
+        await abortMergeIfNeeded(workspaceDir);
+        const theirsMerge = await tryGit(["merge", "--no-edit", "-X", "theirs", `refs/remotes/origin/${repoInfo.defaultBranch}`], { cwd: workspaceDir });
+        if (theirsMerge.exitCode !== 0) {
+          await abortMergeIfNeeded(workspaceDir);
+          logger.info("Worker repo has unrelated history; resetting to remote branch");
+          await runGit(["reset", "--hard", `refs/remotes/origin/${repoInfo.defaultBranch}`], { cwd: workspaceDir });
+        }
+      }
     }
   } else {
     if (!repoInfo.bundleUrl) {
@@ -321,7 +368,21 @@ async function syncWorkerRepoUnlocked(
       await checkoutTrackingBranch(workspaceDir, repoInfo.defaultBranch, `refs/remotes/teamclaw/${repoInfo.defaultBranch}`);
       const mergeResult = await tryGit(["merge", "--ff-only", `refs/remotes/teamclaw/${repoInfo.defaultBranch}`], { cwd: workspaceDir });
       if (mergeResult.exitCode !== 0) {
-        throw new Error(`Failed to fast-forward worker checkout from the controller bundle: ${formatCommandError("git merge", mergeResult)}`);
+        // Worker has local commits that diverge from controller — fall back to merge.
+        const regularMerge = await tryGit(["merge", "--no-edit", `refs/remotes/teamclaw/${repoInfo.defaultBranch}`], { cwd: workspaceDir });
+        if (regularMerge.exitCode !== 0) {
+          await abortMergeIfNeeded(workspaceDir);
+          const theirsMerge = await tryGit(["merge", "--no-edit", "-X", "theirs", `refs/remotes/teamclaw/${repoInfo.defaultBranch}`], { cwd: workspaceDir });
+          if (theirsMerge.exitCode !== 0) {
+            await abortMergeIfNeeded(workspaceDir);
+            // Final fallback: worker history is completely unrelated (e.g. fresh
+            // container with auto-committed workspace files).  Adopt the
+            // controller's branch wholesale — this is safe because the
+            // controller is the source of truth for repo state.
+            logger.info("Worker repo has unrelated history; resetting to controller branch");
+            await runGit(["reset", "--hard", `refs/remotes/teamclaw/${repoInfo.defaultBranch}`], { cwd: workspaceDir });
+          }
+        }
       }
     } finally {
       await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {
@@ -348,7 +409,7 @@ export async function publishWorkerRepo(
     role?: string;
   },
 ): Promise<RepoPublishResult> {
-  const workspaceDir = resolveDefaultOpenClawWorkspaceDir();
+  const workspaceDir = resolveTeamClawWorkspaceDir();
   return await withRepoLock(workspaceDir, async () => publishWorkerRepoUnlocked(config, logger, controllerUrl, repoInfo, meta, workspaceDir));
 }
 
@@ -421,32 +482,51 @@ async function publishWorkerRepoUnlocked(
   const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "teamclaw-worker-publish-"));
   const bundlePath = path.join(tempDir, "worker.bundle");
   try {
-    await runGit(["bundle", "create", bundlePath, repoInfo.defaultBranch], { cwd: workspaceDir });
-    const bundle = await fs.readFile(bundlePath);
-    const importUrl = new URL(resolveApiUrl(repoInfo.importUrl, controllerUrl));
-    importUrl.searchParams.set("taskId", meta.taskId);
-    importUrl.searchParams.set("workerId", meta.workerId);
-    if (meta.role) {
-      importUrl.searchParams.set("role", meta.role);
-    }
+    for (let attempt = 0; attempt <= BUNDLE_IMPORT_MAX_RETRIES; attempt++) {
+      if (attempt > 0) {
+        // Before retry, rebase local worker commits onto the latest controller state
+        // so the next bundle is based on the current controller HEAD.
+        await new Promise<void>((resolve) => setTimeout(resolve, BUNDLE_IMPORT_RETRY_DELAY_MS * attempt));
+        await tryRebaseWorkerOntoController(workspaceDir, repoInfo, controllerUrl, config, logger);
+      }
 
-    const res = await fetch(importUrl.toString(), {
-      method: "POST",
-      headers: { "Content-Type": "application/octet-stream" },
-      body: bundle,
-    });
+      await runGit(["bundle", "create", bundlePath, repoInfo.defaultBranch], { cwd: workspaceDir });
+      const bundle = await fs.readFile(bundlePath);
+      const importUrl = new URL(resolveApiUrl(repoInfo.importUrl, controllerUrl));
+      importUrl.searchParams.set("taskId", meta.taskId);
+      importUrl.searchParams.set("workerId", meta.workerId);
+      if (meta.role) {
+        importUrl.searchParams.set("role", meta.role);
+      }
+
+      const res = await fetch(importUrl.toString(), {
+        method: "POST",
+        headers: { "Content-Type": "application/octet-stream" },
+        body: bundle,
+      });
+
+      if (res.ok) {
+        const payload = await res.json() as { repo?: GitRepoState; message?: string };
+        return {
+          repo: payload.repo ?? await readGitRepoState(config, false),
+          published: true,
+          message: payload.message ?? `Imported bundle for task ${meta.taskId}.`,
+        };
+      }
 
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`Bundle import failed with status ${res.status}: ${text}`);
+      // Only retry on 409 Conflict — other errors are not worth retrying.
+      if (res.status !== 409 || attempt === BUNDLE_IMPORT_MAX_RETRIES) {
+        const text = await res.text();
+        throw new Error(`Bundle import failed with status ${res.status}: ${text}`);
+      }
+
+      logger.warn(
+        `Worker: bundle import for task ${meta.taskId} returned 409 (attempt ${attempt + 1}/${BUNDLE_IMPORT_MAX_RETRIES}); rebasing onto controller HEAD and retrying.`,
+      );
     }
 
-    const payload = await res.json() as { repo?: GitRepoState; message?: string };
-    return {
-      repo: payload.repo ?? await readGitRepoState(config, false),
-      published: true,
-      message: payload.message ?? `Imported bundle for task ${meta.taskId}.`,
-    };
+    // Should not reach here, but satisfy TypeScript.
+    throw new Error("Bundle import failed after all retries");
   } finally {
     await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {
       // best-effort temp cleanup
@@ -458,7 +538,7 @@ export async function readGitRepoState(
   config: PluginConfig,
   remoteReady: boolean,
 ): Promise<GitRepoState> {
-  const workspaceDir = resolveDefaultOpenClawWorkspaceDir();
+  const workspaceDir = resolveTeamClawWorkspaceDir();
   const headCommit = await revParseOrEmpty(workspaceDir, "HEAD");
   const headSummary = headCommit
     ? (await runGit(["log", "-1", "--pretty=%s"], { cwd: workspaceDir })).stdout.trim() || undefined
@@ -599,6 +679,77 @@ async function abortMergeIfNeeded(workspaceDir: string): Promise<void> {
   await tryGit(["merge", "--abort"], { cwd: workspaceDir });
 }
 
+/**
+ * Fetch the latest controller bundle and rebase local commits on top.
+ * Used as a recovery step when a bundle import fails with 409 Conflict.
+ */
+async function tryRebaseWorkerOntoController(
+  workspaceDir: string,
+  repoInfo: RepoSyncInfo,
+  controllerUrl: string,
+  config: PluginConfig,
+  logger: PluginLogger,
+): Promise<void> {
+  try {
+    if (repoInfo.mode === "shared") {
+      return;
+    }
+
+    // Build the bundle URL based on mode
+    const bundleUrlSuffix = repoInfo.mode === "remote" ? repoInfo.remoteUrl : repoInfo.bundleUrl;
+    if (!bundleUrlSuffix) {
+      return;
+    }
+
+    if (repoInfo.mode === "remote") {
+      // Remote mode: fetch from origin and rebase
+      await runGit(["fetch", "origin", repoInfo.defaultBranch], { cwd: workspaceDir });
+      const remoteRef = `refs/remotes/origin/${repoInfo.defaultBranch}`;
+      if (!await revParseOrEmpty(workspaceDir, remoteRef)) {
+        return;
+      }
+      const rebaseResult = await tryGit(["rebase", remoteRef], { cwd: workspaceDir });
+      if (rebaseResult.exitCode !== 0) {
+        await tryGit(["rebase", "--abort"], { cwd: workspaceDir });
+        // Fall back to merge if rebase fails
+        const mergeResult = await tryGit(["merge", "--no-edit", "-X", "theirs", remoteRef], { cwd: workspaceDir });
+        if (mergeResult.exitCode !== 0) {
+          await abortMergeIfNeeded(workspaceDir);
+          logger.warn("Worker: failed to rebase or merge onto controller state; will retry bundle as-is.");
+        }
+      }
+    } else {
+      // Bundle mode: download controller bundle, fetch it, and rebase
+      const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "teamclaw-worker-rebase-"));
+      const tempBundlePath = path.join(tempDir, "controller.bundle");
+      try {
+        const res = await fetch(resolveApiUrl(bundleUrlSuffix, controllerUrl));
+        if (!res.ok) {
+          logger.warn(`Worker: failed to download controller bundle for rebase (status ${res.status}); will retry as-is.`);
+          return;
+        }
+        const buffer = Buffer.from(await res.arrayBuffer());
+        await fs.writeFile(tempBundlePath, buffer);
+        const remoteBranch = `refs/remotes/teamclaw/${repoInfo.defaultBranch}`;
+        await runGit(["fetch", tempBundlePath, `refs/heads/${repoInfo.defaultBranch}:${remoteBranch}`], { cwd: workspaceDir });
+        const rebaseResult = await tryGit(["rebase", remoteBranch], { cwd: workspaceDir });
+        if (rebaseResult.exitCode !== 0) {
+          await tryGit(["rebase", "--abort"], { cwd: workspaceDir });
+          const mergeResult = await tryGit(["merge", "--no-edit", "-X", "theirs", remoteBranch], { cwd: workspaceDir });
+          if (mergeResult.exitCode !== 0) {
+            await abortMergeIfNeeded(workspaceDir);
+            logger.warn("Worker: failed to rebase or merge onto controller state; will retry bundle as-is.");
+          }
+        }
+      } finally {
+        await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+      }
+    }
+  } catch (err) {
+    logger.warn(`Worker: rebase onto controller failed: ${err instanceof Error ? err.message : String(err)}; will retry bundle as-is.`);
+  }
+}
+
 async function pathExists(filePath: string): Promise<boolean> {
   try {
     await fs.access(filePath);

package/src/identity.ts

@@ -89,8 +89,18 @@ export class IdentityManager {
 
     const roleDef = getRole(this.config.role);
     const workerId = requestedWorkerId ?? generateId();
-    const localIp = getLocalIp(new URL(controllerUrl).hostname);
-    const workerUrl = `http://${localIp}:${this.config.port}`;
+    const controllerHost = new URL(controllerUrl).hostname;
+    // Prefer explicit override (set by provisioner for Docker/K8s workers),
+    // then detected IP (works for bridge-network containers and real hosts),
+    // then os.hostname() as last resort.
+    const advertisedHost =
+      process.env.TEAMCLAW_ADVERTISE_HOST?.trim() ||
+      getLocalIp(controllerHost) ||
+      os.hostname();
+    const advertisedPort = process.env.TEAMCLAW_ADVERTISE_PORT?.trim()
+      ? Number(process.env.TEAMCLAW_ADVERTISE_PORT.trim())
+      : this.config.port;
+    const workerUrl = `http://${advertisedHost}:${advertisedPort}`;
 
     const registration = createRegistrationRequest(
       workerId,

package/src/interaction-contracts.ts

@@ -223,6 +223,7 @@ export function normalizeWorkerTaskResultContract(raw: unknown): WorkerTaskResul
     followUps: normalizeResultFollowUps(input.followUps),
     questions: normalizeContractStringList(input.questions),
     notes: normalizeOptionalContractText(input.notes),
+    discoveredPatterns: normalizeContractStringList(input.discoveredPatterns),
   };
 }
 
@@ -315,7 +316,12 @@ function normalizeResultDeliverables(raw: unknown): WorkerTaskResultDeliverable[
         : "note";
       const value = typeof entry.value === "string" ? entry.value.trim() : "";
       const summary = normalizeOptionalContractText(entry.summary);
-      return value ? { kind, value, summary } : null;
+      const artifactType = typeof entry.artifactType === "string" ? entry.artifactType as WorkerTaskResultDeliverable["artifactType"] : undefined;
+      const previewCommand = normalizeOptionalContractText(entry.previewCommand);
+      const previewCwd = normalizeOptionalContractText(entry.previewCwd);
+      const previewReadyPath = normalizeOptionalContractText(entry.previewReadyPath);
+      const liveUrl = normalizeOptionalContractText(entry.liveUrl);
+      return value ? { kind, value, summary, artifactType, previewCommand, previewCwd, previewReadyPath, liveUrl } : null;
     })
     .filter((entry): entry is WorkerTaskResultDeliverable => !!entry);
 }
@@ -426,6 +432,30 @@ function extractQuestionOrBulletLines(text: string, maxItems: number, matcher?:
   return Array.from(new Set(lines.map((line) => summarizeContractText(line, 220)))).slice(0, maxItems);
 }
 
+const WEB_HTML_FILENAMES = new Set(["index.html", "app.html", "main.html", "home.html"]);
+
+/**
+ * Default preview command used when the worker does not provide one.
+ * This is a minimal static file server — the worker (LLM) is responsible
+ * for providing the real, framework-appropriate command via previewCommand
+ * in its result contract.
+ */
+function inferPreviewCommand(_cwd: string, _resultText: string, _filePaths: string[]): string {
+  return "npx -y serve -l {PORT}";
+}
+
+function isWebHtmlPath(filePath: string): boolean {
+  const segments = filePath.replace(/\\/gu, "/").split("/");
+  const filename = segments[segments.length - 1] ?? "";
+  if (!filename.toLowerCase().endsWith(".html") && !filename.toLowerCase().endsWith(".htm")) {
+    return false;
+  }
+  if (filename.startsWith(".") || filename.includes(".config.") || filename.includes(".test.") || filename.includes(".spec.")) {
+    return false;
+  }
+  return true;
+}
+
 function inferResultDeliverables(result: string, error?: string): WorkerTaskResultDeliverable[] {
   if (error) {
     return [{
@@ -436,10 +466,31 @@ function inferResultDeliverables(result: string, error?: string): WorkerTaskResu
   }
 
   const deliverables: WorkerTaskResultDeliverable[] = [];
-  const pathMatches = Array.from(result.matchAll(/(?:^|[\s:(])([A-Za-z0-9_./-]+\.[A-Za-z0-9_-]+)/g))
+  let webAppInferred = false;
+  const pathMatches = Array.from(result.matchAll(/(?:^|[\s:(`])([A-Za-z0-9_./-]+\.[A-Za-z0-9_-]+)/g))
     .map((match) => match[1])
     .filter(Boolean);
-  for (const filePath of Array.from(new Set(pathMatches)).slice(0, 5)) {
+  const uniquePaths = Array.from(new Set(pathMatches)).slice(0, 5);
+  for (const filePath of uniquePaths) {
+    if (!webAppInferred && isWebHtmlPath(filePath)) {
+      const segments = filePath.replace(/\\/gu, "/").split("/");
+      const filename = segments[segments.length - 1] ?? "";
+      const dirname = segments.length > 1 ? segments.slice(0, -1).join("/") : ".";
+      const isTopLevelHtml = WEB_HTML_FILENAMES.has(filename);
+      if (isTopLevelHtml || filename.toLowerCase().endsWith(".html")) {
+        webAppInferred = true;
+        deliverables.push({
+          kind: "directory",
+          value: dirname,
+          summary: `Web application at ${dirname}`,
+          artifactType: "web-app",
+          previewCommand: inferPreviewCommand(dirname, result, uniquePaths),
+          previewCwd: dirname,
+          previewReadyPath: "/",
+        });
+        continue;
+      }
+    }
     deliverables.push({
       kind: "file",
       value: filePath,
@@ -457,3 +508,128 @@ function inferResultDeliverables(result: string, error?: string): WorkerTaskResu
     summary: "Backfilled from the worker's final reply.",
   }];
 }
+
+/**
+ * Enrich existing deliverables with preview fields (artifactType, previewCommand, etc.)
+ * by inferring from the raw result text.
+ *
+ * This function only enriches when the worker did NOT already provide these fields.
+ * When the worker (LLM) submits a proper result contract with previewCommand and
+ * artifactType, we trust it completely — it knows its own code better than we do.
+ *
+ * Returns the contract with enriched deliverables if any enrichment happened, or null
+ * if no enrichment was needed.
+ */
+export function enrichDeliverablesWithPreviewInference(
+  contract: WorkerTaskResultContract,
+  resultText: string,
+): WorkerTaskResultContract | null {
+  const { deliverables } = contract;
+  const existingWebApp = deliverables.find((d) => d.artifactType === "web-app");
+  if (existingWebApp) {
+    // Worker already provided a web-app with a real previewCommand — trust it.
+    if (existingWebApp.previewCommand?.trim()) {
+      return null;
+    }
+    // Worker declared web-app but no command — try to provide a fallback command.
+    const cwd = existingWebApp.previewCwd?.trim();
+    if (cwd && cwd !== "." && cwd !== "./") {
+      // Has a real cwd but no command — provide generic static serve fallback
+      existingWebApp.previewCommand = inferPreviewCommand(cwd, resultText, deliverables.map((d) => d.value ?? ""));
+      return { ...contract, deliverables };
+    }
+  }
+
+  // Strategy 1: Extract file paths from result text to detect HTML files
+  const allSources = [resultText, ...deliverables.map((d) => d.summary ?? "")];
+  const pathMatches = Array.from(
+    allSources.join("\n").matchAll(/(?:^|[\s:(,`])([A-Za-z0-9_./-]+\.[A-Za-z0-9_-]+)/g),
+  )
+    .map((match) => match[1])
+    .filter(Boolean);
+
+  for (const filePath of Array.from(new Set(pathMatches)).slice(0, 5)) {
+    if (isWebHtmlPath(filePath)) {
+      const segments = filePath.replace(/\\/gu, "/").split("/");
+      const filename = segments[segments.length - 1] ?? "";
+      const dirname = segments.length > 1 ? segments.slice(0, -1).join("/") : ".";
+      if (!filename.toLowerCase().endsWith(".html") && !filename.toLowerCase().endsWith(".htm")) {
+        continue;
+      }
+      const allDeliverablePaths = deliverables.map((d) => d.value ?? "");
+      const matchingIndex = deliverables.findIndex((d) =>
+        d.kind === "directory"
+          && filePath.replace(/\\/gu, "/").startsWith(
+            d.value?.replace(/\\/gu, "/").replace(/\/$/u, ""),
+          ),
+      );
+      if (matchingIndex >= 0) {
+        deliverables[matchingIndex] = {
+          ...deliverables[matchingIndex],
+          artifactType: "web-app",
+          previewCommand: inferPreviewCommand(dirname, resultText, allDeliverablePaths),
+          previewCwd: dirname,
+          previewReadyPath: "/",
+          summary: deliverables[matchingIndex].summary || `Web application at ${dirname}`,
+        };
+      } else {
+        deliverables.push({
+          kind: "directory",
+          value: dirname,
+          summary: `Web application at ${dirname}`,
+          artifactType: "web-app",
+          previewCommand: inferPreviewCommand(dirname, resultText, allDeliverablePaths),
+          previewCwd: dirname,
+          previewReadyPath: "/",
+        });
+      }
+      return { ...contract, deliverables };
+    }
+  }
+
+  // Strategy 2: If result text mentions HTML/web/blog/site keywords and there's a
+  // directory deliverable without artifactType, infer web-app from the directory itself.
+  const webKeywords = /\b(html|web\s*app|web\s*site|blog|index\.html|app\.html|homepage)\b/i;
+  const hasWebKeywords = webKeywords.test(resultText) || deliverables.some((d) => webKeywords.test(d.summary ?? ""));
+
+  if (hasWebKeywords) {
+    const dirDeliverable = deliverables.find(
+      (d) => d.kind === "directory" && !d.artifactType && d.value,
+    );
+    if (dirDeliverable) {
+      const cwd = dirDeliverable.value.replace(/\/$/u, "");
+      const allDeliverablePaths = deliverables.map((d) => d.value ?? "");
+      deliverables[deliverables.indexOf(dirDeliverable)] = {
+        ...dirDeliverable,
+        artifactType: "web-app",
+        previewCommand: inferPreviewCommand(cwd, resultText, allDeliverablePaths),
+        previewCwd: cwd,
+        previewReadyPath: "/",
+        summary: dirDeliverable.summary || `Web application at ${cwd}`,
+      };
+      return { ...contract, deliverables };
+    }
+  }
+
+  // Strategy 3: Extract directory paths that contain HTML files from result text
+  // (e.g. "blog/index.html" → directory "blog"). This handles cases where deliverables
+  // are all "note" type but result text references HTML files in directories.
+  const dirHtmlPattern = /([A-Za-z0-9_.-]+\/)[A-Za-z0-9_.-]+\.html\b/g;
+  const dirMatches = Array.from(resultText.matchAll(dirHtmlPattern)).map((m) => m[1].replace(/\/$/u, ""));
+  const uniqueDirs = Array.from(new Set(dirMatches));
+  if (uniqueDirs.length > 0 && hasWebKeywords) {
+    const dirname = uniqueDirs[0];
+    deliverables.push({
+      kind: "directory",
+      value: dirname,
+      summary: `Web application at ${dirname}`,
+      artifactType: "web-app",
+      previewCommand: inferPreviewCommand(dirname, resultText, [dirname]),
+      previewCwd: dirname,
+      previewReadyPath: "/",
+    });
+    return { ...contract, deliverables };
+  }
+
+  return null;
+}