@teamclaws/teamclaw 2026.4.2-2 → 2026.4.2-4

package/README.md

@@ -6,7 +6,8 @@ It supports:
 
 - `controller` / `worker` modes
 - externally registered workers
-- clarifications, workspace browsing, and Web UI
+- adaptive kickoff planning for medium/complex work, with per-role assessments before task creation
+- clarifications, workspace browsing, controller UI visibility, and a matching desktop client
 - Git-based collaboration
 - on-demand worker provisioning with `process`, `docker`, and `kubernetes`
 
@@ -25,9 +26,12 @@ This installer can:
 - install/update the TeamClaw plugin in OpenClaw
 - detect your local `openclaw.json`
 - let you choose the installation mode
+- support dedicated worker-only installs with `--install-mode worker`
 - let you choose a model from the models already defined in OpenClaw
 - let you choose the OpenClaw workspace directory
 - default TeamClaw to a dedicated `teamclaw` agent/workspace instead of reusing `main`
+- copy the effective host model into the dedicated TeamClaw agent config when independent mode is used
+- bootstrap TeamClaw auth profiles from the host OpenClaw auth store when available
 - prefill Docker/Kubernetes provisioning with the published TeamClaw runtime image
 - prefill Docker workspace persistence with a named volume and Kubernetes persistence with a PVC name
 
@@ -36,6 +40,8 @@ By default, guided install now uses an independent TeamClaw agent/workspace layo
 - `agent:teamclaw:*` sessions
 - sibling workspace such as `~/.openclaw/workspace-teamclaw`
 
+In practice, this means TeamClaw keeps its own agent state, workspace, and auth-profile copy instead of reusing the host `main` agent. Use this default unless you explicitly need legacy compatibility with a shared `main` workspace.
+
 For advanced compatibility only, you can force the legacy shared-`main` layout:
 
 ```bash
@@ -65,6 +71,15 @@ For maintainers, TeamClaw now uses two release paths:
 1. **npm package** — published by GitHub Actions via `.github/workflows/teamclaw-plugin-npm-release.yml`
 2. **ClawHub code plugin + bundled skills** — published manually from the CLI
 
+The npm publish workflow runs automatically when:
+
+- a tag matching `v*` is pushed
+- or relevant package files change on `main` (`src/**`, `.github/workflows/teamclaw-plugin-npm-release.yml`, `scripts/sync-teamclaw-plugin-manifest.mjs`, `scripts/teamclaw-package-check.mjs`, `scripts/teamclaw-npm-publish.sh`)
+
+It also supports `workflow_dispatch` for a specific commit SHA on `main`.
+
+Before the first real npm publish, GitHub must already be configured for npm trusted publishing with the `npm-release` environment and this workflow file.
+
 Before either release path, sync and validate the generated plugin manifest:
 
 ```bash
@@ -95,7 +110,7 @@ For a first-time setup, the safest path is:
 2. Validate the workflow with a small smoke-test task
 3. Expand to external workers, Docker, or Kubernetes after the basics are working
 
-When on-demand provisioning is enabled, TeamClaw now treats controller startup as a readiness phase, not just a process-up check. During that warm-up, `/api/v1/health` returns a non-OK status until the controller has verified writable runtime paths and successfully brought the configured startup worker roles online.
+When on-demand provisioning is enabled, TeamClaw now treats controller startup as a readiness phase, not just a process-up check. During that warm-up, `/api/v1/health` returns a non-OK status until the controller has verified writable runtime paths and successfully brought the configured startup worker roles online. If `workerProvisioningRoles` is empty, startup readiness defaults to waiting for a warm `developer` worker.
 
 ## Documentation
 

package/cli.mjs

@@ -63,8 +63,8 @@ const INSTALL_MODE_OPTIONS = [
   },
   {
     value: "controller-manual",
-    label: "Controller only + external workers",
-    hint: "Use separate OpenClaw installs for workers.",
+    label: "Local controller + default on-demand workers",
+    hint: "Lean same-host setup; writes workerProvisioningRoles=[] and workerProvisioningMaxPerRole=1.",
   },
   {
     value: "controller-docker",
@@ -776,7 +776,10 @@ function isControllerInstallMode(installMode) {
 }
 
 function isOnDemandControllerInstallMode(installMode) {
-  return installMode === "controller-process" || installMode === "controller-docker" || installMode === "controller-kubernetes";
+  return installMode === "controller-manual" ||
+    installMode === "controller-process" ||
+    installMode === "controller-docker" ||
+    installMode === "controller-kubernetes";
 }
 
 function describeProvisioningRoles(roles) {
@@ -1360,7 +1363,7 @@ async function collectInstallChoices(configPath, config, prompter, options) {
 
   const provisioningRoles = await promptOptionalRoleList(
     prompter,
-    "Preferred on-demand roles (comma-separated, leave empty for controller-decided defaults)",
+    "Preferred on-demand roles (comma-separated, leave empty to keep workerProvisioningRoles empty and let startup readiness default to a warm developer worker)",
     resolveDefaultProvisioningRoles(existingTeamClaw),
   );
   const maxPerRole = await prompter.number({
@@ -1368,7 +1371,7 @@ async function collectInstallChoices(configPath, config, prompter, options) {
     defaultValue:
       typeof existingTeamClaw.workerProvisioningMaxPerRole === "number" && existingTeamClaw.workerProvisioningMaxPerRole >= 1
         ? existingTeamClaw.workerProvisioningMaxPerRole
-        : 2,
+        : 10,
     min: 1,
     max: 50,
   });
@@ -1674,7 +1677,7 @@ function applyInstallerChoices(config, choices, configPath) {
     teamclawConfig.workerProvisioningDisabled = true;
     teamclawConfig.workerProvisioningControllerUrl = "";
     teamclawConfig.workerProvisioningRoles = [];
-    teamclawConfig.workerProvisioningMaxPerRole = 1;
+    teamclawConfig.workerProvisioningMaxPerRole = 10;
     teamclawConfig.workerProvisioningImage = "";
     teamclawConfig.workerProvisioningPassEnv = [];
     teamclawConfig.workerProvisioningExtraEnv = {};
@@ -1690,11 +1693,11 @@ function applyInstallerChoices(config, choices, configPath) {
     delete teamclawConfig.role;
 
     if (choices.installMode === "controller-manual") {
-      teamclawConfig.workerProvisioningType = "none";
-      teamclawConfig.workerProvisioningDisabled = true;
+      teamclawConfig.workerProvisioningType = "process";
+      teamclawConfig.workerProvisioningDisabled = false;
       teamclawConfig.workerProvisioningControllerUrl = "";
       teamclawConfig.workerProvisioningRoles = [];
-      teamclawConfig.workerProvisioningMaxPerRole = 1;
+      teamclawConfig.workerProvisioningMaxPerRole = 10;
       teamclawConfig.workerProvisioningImage = "";
       teamclawConfig.workerProvisioningPassEnv = [];
       teamclawConfig.workerProvisioningExtraEnv = {};
@@ -1963,7 +1966,7 @@ async function runInstall(options) {
     } else if (choices.installMode === "controller-kubernetes") {
       prompter.note("Before using Kubernetes provisioning, make sure kubectl, namespace access, and the worker image are ready.");
     } else if (choices.installMode === "controller-manual") {
-      prompter.note("Next step: run this installer again on your worker nodes with the dedicated worker mode.");
+      prompter.note("Next step: open the local TeamClaw UI and let it provision local workers on demand.");
     } else if (choices.installMode === "worker") {
       prompter.note("Next step: start this worker node so it can register with the controller.");
     }

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "teamclaw",
   "name": "TeamClaw",
   "description": "Virtual team collaboration - multiple OpenClaw instances form a virtual software company with role-based task routing.",
-  "version": "2026.4.2-2",
+  "version": "2026.4.2-4",
   "skills": [
     "./skills"
   ],
@@ -61,7 +61,7 @@
     },
     "processModel": {
       "label": "Process Model",
-      "help": "TeamClaw runs workers as separate gateway processes"
+      "help": "TeamClaw runs workers as local or provisioned gateway processes"
     },
     "workerProvisioningType": {
       "label": "On-demand Worker Provider",
@@ -234,7 +234,7 @@
           "multi"
         ],
         "default": "multi",
-        "description": "Worker execution model: TeamClaw runs workers as separate gateway processes"
+        "description": "Worker execution model: TeamClaw runs workers as local or provisioned gateway processes"
       },
       "workerProvisioningType": {
         "type": "string",
@@ -260,7 +260,7 @@
       "workerProvisioningRoles": {
         "type": "array",
         "default": [],
-        "description": "Preferred on-demand roles; task-required roles can still launch automatically. Empty means controller-decided defaults across all roles",
+        "description": "Preferred on-demand roles; task-required roles can still launch automatically. Empty means no preferred startup role list, so startup readiness falls back to a warm developer worker",
         "items": {
           "type": "string",
           "enum": [
@@ -284,7 +284,7 @@
       },
       "workerProvisioningMaxPerRole": {
         "type": "number",
-        "default": 3,
+        "default": 10,
         "description": "Maximum on-demand workers to launch per role"
       },
       "workerProvisioningIdleTtlMs": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamclaws/teamclaw",
-  "version": "2026.4.2-2",
+  "version": "2026.4.2-4",
   "description": "OpenClaw virtual software team orchestration plugin",
   "private": false,
   "keywords": [

package/skills/teamclaw/SKILL.md

@@ -203,7 +203,7 @@ Mention this to users who prefer a visual overview.
 | Issue | Solution |
 |-------|----------|
 | Health check fails | Ensure TeamClaw plugin is enabled in controller mode: `openclaw plugins list` |
-| No workers available | Check processModel config; single-process creates workers automatically |
+| No workers available | Check `workerProvisioningType` / `workerProvisioningDisabled`; local installs should usually use process provisioning |
 | Intake times out | Increase `taskTimeoutMs` in TeamClaw config; ensure AI model is responsive |
 | Task stuck in pending | No idle worker for the assigned role; check `GET /api/v1/workers` |
 | Clarification blocking | Answer pending clarifications via `POST /api/v1/clarifications/:id/answer` |

package/skills/teamclaw/references/api-quick-ref.md

@@ -10,7 +10,7 @@ Default: `http://127.0.0.1:9527`
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/v1/health` | Health check → `{"status":"ok"}` |
+| GET | `/api/v1/health` | Health/readiness check; may report a non-OK startup readiness state until required warm workers are online |
 | GET | `/api/v1/team/status` | Full team snapshot (workers, tasks, runs, clarifications) |
 | GET | `/api/v1/roles` | List all available roles |
 

package/skills/teamclaw-setup/references/install-modes.md

@@ -48,7 +48,7 @@ Minimal TeamClaw plugin block:
   "workerProvisioningType": "process",
   "workerProvisioningRoles": [],
   "workerProvisioningMinPerRole": 0,
-  "workerProvisioningMaxPerRole": 2,
+  "workerProvisioningMaxPerRole": 10,
   "workerProvisioningIdleTtlMs": 120000,
   "workerProvisioningStartupTimeoutMs": 120000
 }
@@ -56,6 +56,12 @@ Minimal TeamClaw plugin block:
 
 Use this first because it avoids multi-machine networking while still exercising the real controller, provisioned workers, UI, messages, clarifications, and git-backed workspace flow.
 
+If the user is specifically choosing install modes through the guided installer, remember the resulting config differs by mode:
+
+- `controller-manual` writes `workerProvisioningType: "process"` and `workerProvisioningRoles: []`, so startup readiness falls back to a warm `developer` worker
+- `controller-process` writes `workerProvisioningType: "process"` and uses the chosen roles/max-per-role
+- `worker` disables provisioning on that node
+
 ## 4. Worker-only topology
 
 Use this only when a controller already exists elsewhere:
@@ -83,7 +89,7 @@ Use this when the controller should launch same-machine workers only as needed:
   "teamName": "my-team",
   "workerProvisioningType": "process",
   "workerProvisioningMinPerRole": 0,
-  "workerProvisioningMaxPerRole": 2,
+  "workerProvisioningMaxPerRole": 10,
   "workerProvisioningIdleTtlMs": 120000,
   "workerProvisioningStartupTimeoutMs": 120000
 }
@@ -103,7 +109,7 @@ Use this when the user already has Docker and wants containerized workers:
   "workerProvisioningImage": "ghcr.io/topcheer/teamclaw-openclaw:latest",
   "workerProvisioningWorkspaceRoot": "/workspace-root",
   "workerProvisioningDockerWorkspaceVolume": "teamclaw-workspaces",
-  "workerProvisioningMaxPerRole": 3
+  "workerProvisioningMaxPerRole": 10
 }
 ```
 
@@ -126,7 +132,7 @@ Use this only when the user already runs the controller in or behind a reachable
   "workerProvisioningImage": "ghcr.io/topcheer/teamclaw-openclaw:latest",
   "workerProvisioningWorkspaceRoot": "/workspace-root",
   "workerProvisioningKubernetesWorkspacePersistentVolumeClaim": "teamclaw-workspace",
-  "workerProvisioningMaxPerRole": 2
+  "workerProvisioningMaxPerRole": 10
 }
 ```
 

package/skills/teamclaw-setup/references/validation-checklist.md

@@ -14,6 +14,8 @@ Expected shape:
 {"status":"ok","mode":"controller", ...}
 ```
 
+If on-demand provisioning is enabled, `/api/v1/health` can temporarily return a non-OK readiness state during warm-up. When `workerProvisioningRoles` is empty, readiness defaults to waiting for a warm `developer` worker.
+
 Also point them to:
 
 ```text
@@ -67,7 +69,7 @@ If OpenClaw times out first, users often think TeamClaw is broken when the real
 
 Treat the install as successful only when:
 
-1. controller health is `ok`
+1. controller health is `ok` after startup readiness finishes
 2. expected workers appear in the UI or status view
 3. the smoke-test task completes
 4. files appear in the workspace

package/src/config.ts

@@ -79,7 +79,7 @@ function buildConfigSchema() {
           type: "string" as const,
           enum: ["multi"],
           default: "multi",
-          description: "Worker execution model: TeamClaw runs workers as separate gateway processes",
+          description: "Worker execution model: TeamClaw runs workers as local or provisioned gateway processes",
         },
         workerProvisioningType: {
           type: "string" as const,
@@ -100,7 +100,7 @@ function buildConfigSchema() {
         workerProvisioningRoles: {
           type: "array" as const,
           default: [],
-          description: "Preferred on-demand roles; task-required roles can still launch automatically. Empty means controller-decided defaults across all roles",
+          description: "Preferred on-demand roles; task-required roles can still launch automatically. Empty means no preferred startup role list, so startup readiness falls back to a warm developer worker",
           items: {
             type: "string" as const,
             enum: ROLE_IDS,
@@ -113,7 +113,7 @@ function buildConfigSchema() {
         },
         workerProvisioningMaxPerRole: {
           type: "number" as const,
-          default: 3,
+          default: 10,
           description: "Maximum on-demand workers to launch per role",
         },
         workerProvisioningIdleTtlMs: {
@@ -253,7 +253,7 @@ function buildConfigSchema() {
       },
       processModel: {
         label: "Process Model",
-        help: "TeamClaw runs workers as separate gateway processes",
+        help: "TeamClaw runs workers as local or provisioned gateway processes",
       },
       workerProvisioningType: {
         label: "On-demand Worker Provider",

package/src/controller/controller-capacity.ts

@@ -1,13 +1,13 @@
 import type { PluginConfig, TeamState } from "../types.js";
 
 export function hasOnDemandWorkerProvisioning(
-  config: Pick<PluginConfig, "workerProvisioningType" | "processModel">,
+  config: Pick<PluginConfig, "workerProvisioningType" | "workerProvisioningDisabled" | "processModel">,
 ): boolean {
-  return config.workerProvisioningType !== "none";
+  return config.workerProvisioningType !== "none" && config.workerProvisioningDisabled !== true;
 }
 
 export function shouldBlockControllerWithoutWorkers(
-  config: Pick<PluginConfig, "workerProvisioningType" | "processModel">,
+  config: Pick<PluginConfig, "workerProvisioningType" | "workerProvisioningDisabled" | "processModel">,
   state: TeamState | null,
 ): boolean {
   return !!state && Object.keys(state.workers).length === 0 && !hasOnDemandWorkerProvisioning(config);

package/src/controller/http-server.ts

@@ -1427,6 +1427,9 @@ function buildControllerFollowUpMessage(task: TaskInfo, state: TeamState | null)
     "Continue orchestrating this same requirement.",
     "Review the current TeamClaw state before acting.",
     "Create only the next execution-ready task(s) whose prerequisites are now satisfied.",
+    "For any large-scale requirement, prefer parallel fan-out over serial mega-phases: if multiple independent developer workstreams are ready, create all of them now instead of a single umbrella developer task.",
+    "Decompose developer work by module or subsystem with clear file ownership and interfaces so multiple developer workers can collaborate safely in parallel.",
+    "Use TeamClaw's available same-role capacity: create multiple developer tasks when the work can proceed concurrently rather than forcing one developer to carry the whole rewrite alone.",
     "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.",
@@ -1436,6 +1439,37 @@ function buildControllerFollowUpMessage(task: TaskInfo, state: TeamState | null)
   return parts.filter(Boolean).join("\n");
 }
 
+function buildControllerParallelHelpMessage(
+  task: TaskInfo,
+  state: TeamState | null,
+  input: {
+    requestedBy: string;
+    requestedByRole?: RoleId;
+    targetRole?: RoleId;
+    reason: string;
+    requestedWorkerCount?: number;
+    suggestedWorkstreams: string[];
+  },
+): string {
+  const targetRole = input.targetRole || input.requestedByRole || task.assignedRole || "developer";
+  return [
+    buildControllerFollowUpMessage(task, state),
+    "",
+    "## Parallel Help Request",
+    `Current worker ${input.requestedBy} has asked TeamClaw to expand parallel help for role ${targetRole}.`,
+    input.requestedByRole ? `Requesting worker role: ${input.requestedByRole}` : "",
+    typeof input.requestedWorkerCount === "number"
+      ? `Desired same-role worker capacity for this requirement: ${input.requestedWorkerCount}`
+      : "",
+    `Why more parallel help is needed: ${input.reason}`,
+    input.suggestedWorkstreams.length > 0
+      ? `Suggested parallel workstreams:\n${input.suggestedWorkstreams.map((item) => `- ${item}`).join("\n")}`
+      : "",
+    "If the suggested workstreams are genuinely independent, create multiple execution-ready tasks for that role now instead of keeping one giant serial task.",
+    "Reuse active tasks when possible, but if no matching tasks already exist, fan out the work into distinct module- or subsystem-scoped tasks that can run concurrently.",
+  ].filter(Boolean).join("\n");
+}
+
 function buildControllerClarificationAnswerMessage(
   clarification: ClarificationRequest,
   answer: string,
@@ -2644,6 +2678,8 @@ function enrichWithFilesystemHtmlScan(
 
 const MEANINGFUL_PROJECT_CHANGE_EXTENSIONS = new Set([
   ".js", ".jsx", ".ts", ".tsx", ".json", ".html", ".css", ".scss", ".md", ".txt", ".yml", ".yaml",
+  ".go", ".mod", ".sum", ".py", ".rb", ".rs", ".java", ".kt", ".swift", ".c", ".cc", ".cpp", ".h", ".hpp",
+  ".cs", ".php", ".sh", ".bash", ".zsh", ".sql", ".toml", ".ini",
 ]);
 
 const IGNORED_PROJECT_CHANGE_DIRS = new Set([
@@ -2668,7 +2704,57 @@ function taskRequiresMeaningfulProjectChangeGate(task: TaskInfo): boolean {
   return /\b(implement|build|fix|rework|update|add|enhanc|deliver|write|create)\b/u.test(text);
 }
 
-function projectHasMeaningfulFileChanges(task: TaskInfo): boolean {
+function projectHasMeaningfulDeliverableEvidence(
+  task: TaskInfo,
+  contract: WorkerTaskResultContract | undefined,
+): boolean {
+  if (!task.projectDir || !contract) {
+    return false;
+  }
+  const projectRoot = path.join(resolveTeamClawProjectsDir(), task.projectDir);
+  for (const deliverable of contract.deliverables) {
+    if (deliverable.kind !== "file" && deliverable.kind !== "directory") {
+      continue;
+    }
+    const rawValue = deliverable.value.trim().replace(/\\/g, "/");
+    if (!rawValue) {
+      continue;
+    }
+    const normalizedValue = rawValue.startsWith("projects/")
+      ? rawValue.slice("projects/".length)
+      : rawValue;
+    if (
+      normalizedValue !== task.projectDir
+      && !normalizedValue.startsWith(`${task.projectDir}/`)
+    ) {
+      continue;
+    }
+    const relativePath = normalizedValue === task.projectDir
+      ? ""
+      : normalizedValue.slice(task.projectDir.length + 1);
+    const fullPath = relativePath ? path.join(projectRoot, relativePath) : projectRoot;
+    try {
+      const stats = fs.statSync(fullPath);
+      if (stats.isFile()) {
+        return true;
+      }
+      if (stats.isDirectory()) {
+        const entries = fs.readdirSync(fullPath, { withFileTypes: true });
+        if (entries.some((entry) => entry.isFile() || entry.isDirectory())) {
+          return true;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
+
+function projectHasMeaningfulFileChanges(
+  task: TaskInfo,
+  contract?: WorkerTaskResultContract,
+): boolean {
   if (!task.projectDir) {
     return false;
   }
@@ -2714,7 +2800,7 @@ function projectHasMeaningfulFileChanges(task: TaskInfo): boolean {
       }
     }
   }
-  return false;
+  return projectHasMeaningfulDeliverableEvidence(task, contract);
 }
 
 function allowsNoChangeCompletion(
@@ -2982,6 +3068,25 @@ function ensureTaskResultContract(
   return contract;
 }
 
+function buildEffectiveTaskResultContract(
+  task: TaskInfo,
+  result: string,
+  error: string | undefined,
+  submittedContract?: WorkerTaskResultContract,
+): WorkerTaskResultContract {
+  let contract = submittedContract
+    ? filterStaleDeliverables(submittedContract, task.projectDir)
+    : backfillWorkerTaskResultContract(task, result, error);
+  if (!error) {
+    const enriched = enrichDeliverablesWithPreviewInference(contract, result)
+      ?? enrichWithFilesystemHtmlScan(contract, task.projectDir);
+    if (enriched) {
+      contract = enriched;
+    }
+  }
+  return contract;
+}
+
 function buildResultContractSection(task: TaskInfo): string {
   const contract = task.resultContract;
   if (!contract) {
@@ -4078,20 +4183,40 @@ async function handleRequest(
         }, deps);
     }
 
-    if (!error && submittedContract?.outcome === "blocked") {
+    const effectiveContract = buildEffectiveTaskResultContract(currentTask, result, error, submittedContract);
+
+    if (!error && effectiveContract.outcome === "blocked") {
+      updateTeamState((teamState) => {
+        const task = teamState.tasks[taskId];
+        if (!task) {
+          return;
+        }
+        task.resultContract = effectiveContract;
+        task.updatedAt = Date.now();
+      });
+      if (!submittedContract) {
+        recordTaskExecutionEvent(taskId, {
+          type: "lifecycle",
+          phase: "result_contract_backfilled",
+          source: "controller",
+          message: "Worker did not submit a structured result contract; TeamClaw backfilled one from the recorded task result.",
+          workerId: currentTask.assignedWorkerId,
+          role: currentTask.assignedRole,
+        }, deps);
+      }
       const requested = await requestTaskClarification({
         taskId,
         requestedBy: workerId ?? "worker",
         requestedByWorkerId: workerId,
         requestedByRole: currentTask.assignedRole,
-        question: submittedContract.questions[0]
+        question: effectiveContract.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,
+        blockingReason: effectiveContract.blockers[0] ?? effectiveContract.summary,
         context: [
-          submittedContract.notes,
+          effectiveContract.notes,
           result.trim(),
-          submittedContract.keyPoints.length > 0
-            ? `Worker-provided commands/details:\n${submittedContract.keyPoints.join("\n")}`
+          effectiveContract.keyPoints.length > 0
+            ? `Worker-provided commands/details:\n${effectiveContract.keyPoints.join("\n")}`
             : "",
         ].filter(Boolean).join("\n\n"),
       }, deps);
@@ -4116,7 +4241,7 @@ async function handleRequest(
       !error
       && gatedTask
       && taskRequiresMeaningfulProjectChangeGate(gatedTask)
-      && !projectHasMeaningfulFileChanges(gatedTask)
+      && !projectHasMeaningfulFileChanges(gatedTask, effectiveContract)
       && !allowsNoChangeCompletion(gatedTask, submittedContract, result)
     ) {
       error = "Task reported completion but no meaningful project file changes were detected in the assigned project directory.";
@@ -4205,6 +4330,63 @@ async function handleRequest(
     return;
   }
 
+  // POST /api/v1/tasks/:id/parallel-help
+  if (req.method === "POST" && pathname.match(/^\/api\/v1\/tasks\/[^/]+\/parallel-help$/)) {
+    const taskId = pathname.split("/")[4]!;
+    const body = await parseJsonBody(req);
+    const currentTask = getTeamState()?.tasks[taskId];
+    if (!currentTask) {
+      sendError(res, 404, "Task not found");
+      return;
+    }
+    const requestedBy = typeof body.requestedBy === "string" ? body.requestedBy : "";
+    const reason = typeof body.reason === "string" ? body.reason.trim() : "";
+    const requestedByRole = typeof body.requestedByRole === "string" ? body.requestedByRole as RoleId : undefined;
+    const targetRole = typeof body.targetRole === "string" ? body.targetRole as RoleId : undefined;
+    const requestedWorkerCount = typeof body.requestedWorkerCount === "number"
+      ? Math.max(2, Math.min(10, Math.floor(body.requestedWorkerCount)))
+      : undefined;
+    const suggestedWorkstreams = Array.isArray(body.suggestedWorkstreams)
+      ? body.suggestedWorkstreams.map((entry: unknown) => String(entry ?? "").trim()).filter(Boolean)
+      : [];
+    if (!requestedBy || !reason) {
+      sendError(res, 400, "requestedBy and reason are required");
+      return;
+    }
+    const sessionKey = resolveControllerWorkflowSessionKey(currentTask, getTeamState());
+    if (!sessionKey) {
+      sendError(res, 409, "Task is not linked to a controller session");
+      return;
+    }
+    recordTaskExecutionEvent(taskId, {
+      type: "progress",
+      phase: "parallel_help_requested",
+      source: "worker",
+      message: `Worker requested more ${targetRole || requestedByRole || currentTask.assignedRole || "developer"} capacity for parallel work: ${reason}`,
+      workerId: requestedBy,
+      role: requestedByRole,
+    }, deps);
+    const result = await runControllerIntake(
+      buildControllerParallelHelpMessage(currentTask, getTeamState(), {
+        requestedBy,
+        requestedByRole,
+        targetRole,
+        reason,
+        requestedWorkerCount,
+        suggestedWorkstreams,
+      }),
+      sessionKey,
+      deps,
+      {
+        source: "task_follow_up",
+        sourceTaskId: currentTask.id,
+        sourceTaskTitle: currentTask.title,
+      },
+    );
+    sendJson(res, 201, result);
+    return;
+  }
+
   // ==================== Message Routing ====================
 
   // POST /api/v1/controller/manifest

package/src/controller/worker-provisioning.ts

@@ -1416,7 +1416,7 @@ function buildProvisionedWorkerConfig(
   teamclawConfig.workerProvisioningControllerUrl = "";
   teamclawConfig.workerProvisioningRoles = [];
   teamclawConfig.workerProvisioningMinPerRole = 0;
-  teamclawConfig.workerProvisioningMaxPerRole = 1;
+  teamclawConfig.workerProvisioningMaxPerRole = 10;
   teamclawConfig.workerProvisioningIdleTtlMs = controllerConfig.workerProvisioningIdleTtlMs;
   teamclawConfig.workerProvisioningStartupTimeoutMs = controllerConfig.workerProvisioningStartupTimeoutMs;
   teamclawConfig.workerProvisioningImage = "";

package/src/prompt-policy.ts

@@ -45,6 +45,7 @@ export function buildRoleOperatingRules(options: {
     "- You are a team member, not the controller. Complete the current task yourself.",
     "- Stay within your assigned role. Do not switch roles unless the task explicitly asks for cross-role analysis.",
     "- Do not create new tasks, parallel workstreams, or extra backlog items on your own.",
+    "- If the assigned task is clearly too large for one worker but can be split into independent same-role workstreams, ask the controller to expand parallel help instead of silently carrying the whole backlog alone.",
     "- Do not delegate the core work of your current task to another role.",
     "- Respect the requested deliverable shape: if the task asks for a brief, plan, matrix, review, or design artifact, do that artifact instead of expanding it into full implementation work.",
     "- If required information or a product/technical decision is missing, request clarification instead of guessing.",
@@ -81,6 +82,7 @@ export function buildWorkerSessionRules(): string[] {
     "1. Complete only the task assigned to this session.",
     "2. Pending team messages are context, not permission to widen scope.",
     "3. Do NOT create new tasks, duplicate an existing task, or start a parallel task tree.",
+    "3a. If the task is too large for one worker and can be safely split into independent same-role workstreams, use the controller-facing parallel-help tool instead of silently continuing as one giant serial task.",
     "4. If you are blocked by missing information, raise a clarification request and stop instead of guessing.",
     "5. If required infrastructure, credentials, or external tool access are unavailable in this runtime, raise a clarification request and stop instead of faking completion.",
     "6. Respect the task's requested deliverable: briefs, plans, matrices, reviews, and design artifacts are not implementation requests unless the task explicitly asks you to build code.",

package/src/state.ts

@@ -20,6 +20,7 @@ function resolvePluginStateDir(): string {
 }
 
 const STATE_DIR = resolvePluginStateDir();
+const writeQueues = new Map<string, Promise<void>>();
 
 function createEmptyProvisioningState(): TeamProvisioningState {
   return {
@@ -63,6 +64,25 @@ async function ensureDir(dir: string): Promise<void> {
   await fs.mkdir(dir, { recursive: true });
 }
 
+async function writeFileAtomically(filePath: string, contents: string): Promise<void> {
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  await fs.writeFile(tmpPath, contents, "utf8");
+  await fs.rename(tmpPath, filePath);
+}
+
+function enqueueAtomicWrite(filePath: string, contents: string): Promise<void> {
+  const previous = writeQueues.get(filePath) ?? Promise.resolve();
+  const next = previous
+    .catch(() => {})
+    .then(() => writeFileAtomically(filePath, contents));
+  writeQueues.set(filePath, next);
+  return next.finally(() => {
+    if (writeQueues.get(filePath) === next) {
+      writeQueues.delete(filePath);
+    }
+  });
+}
+
 async function loadTeamState(teamName: string): Promise<TeamState | null> {
   const filePath = path.join(STATE_DIR, `${teamName}-team-state.json`);
   try {
@@ -116,7 +136,7 @@ async function saveTeamState(state: TeamState): Promise<void> {
   state.controllerRuns = state.controllerRuns && typeof state.controllerRuns === "object"
     ? state.controllerRuns
     : {};
-  await fs.writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  await enqueueAtomicWrite(filePath, `${JSON.stringify(state, null, 2)}\n`);
 }
 
 async function loadWorkerIdentity(): Promise<WorkerIdentity | null> {
@@ -141,7 +161,7 @@ async function loadWorkerIdentity(): Promise<WorkerIdentity | null> {
 async function saveWorkerIdentity(identity: WorkerIdentity): Promise<void> {
   await ensureDir(STATE_DIR);
   const filePath = path.join(STATE_DIR, "worker-identity.json");
-  await fs.writeFile(filePath, `${JSON.stringify(identity, null, 2)}\n`, "utf8");
+  await enqueueAtomicWrite(filePath, `${JSON.stringify(identity, null, 2)}\n`);
 }
 
 async function clearWorkerIdentity(): Promise<void> {

package/src/types.ts

@@ -562,7 +562,7 @@ export function parsePluginConfig(raw: Record<string, unknown> = {}): PluginConf
     ? raw.heartbeatIntervalMs
     : 10000;
 
-  const processModel: ProcessModel = "multi";
+  const processModel = parseProcessModel(raw.processModel);
 
   const taskTimeoutMs = typeof raw.taskTimeoutMs === "number" && raw.taskTimeoutMs >= 1000
     ? raw.taskTimeoutMs
@@ -717,6 +717,12 @@ function parseProvisioningType(raw: unknown): WorkerProvisioningType {
     : "none";
 }
 
+function parseProcessModel(raw: unknown): ProcessModel {
+  return typeof raw === "string" && raw.trim() === "multi"
+    ? "multi"
+    : "multi";
+}
+
 function parseStringArray(raw: unknown): string[] {
   return Array.isArray(raw)
     ? [...new Set(raw

package/src/worker/tools.ts

@@ -10,11 +10,28 @@ import {
   normalizeWorkerTaskResultContract,
   renderWorkerProgressText,
 } from "../interaction-contracts.js";
+import { loadWorkerIdentity } from "../state.js";
 import type { PluginConfig, WorkerIdentity } from "../types.js";
 import { normalizeClarificationQuestionSchema } from "../controller/orchestration-manifest.js";
 
 const ALLOWED_PROGRESS_STATUSES = new Set(["in_progress", "review"]);
 
+function normalizeProgressText(params: Record<string, unknown>): string {
+  if (typeof params.progress === "string" && params.progress.trim()) {
+    return params.progress.trim();
+  }
+  if (typeof params.summary === "string" && params.summary.trim()) {
+    return params.summary.trim();
+  }
+  if (typeof params.currentStep === "string" && params.currentStep.trim()) {
+    return params.currentStep.trim();
+  }
+  if (typeof params.message === "string" && params.message.trim()) {
+    return params.message.trim();
+  }
+  return "";
+}
+
 export type WorkerToolsDeps = {
   config: PluginConfig;
   getIdentity: () => WorkerIdentity | null;
@@ -23,6 +40,10 @@ export type WorkerToolsDeps = {
 export function createWorkerTools(deps: WorkerToolsDeps) {
   const { config, getIdentity } = deps;
 
+  async function resolveIdentity(): Promise<WorkerIdentity | null> {
+    return getIdentity() ?? await loadWorkerIdentity();
+  }
+
   return [
     {
       name: "teamclaw_ask_peer",
@@ -38,7 +59,7 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
         references: Type.Optional(Type.Array(Type.String({ description: "Relevant task IDs, file paths, or artifact references" }))),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
-        const identity = getIdentity();
+        const identity = await resolveIdentity();
         if (!identity) {
           return { content: [{ type: "text" as const, text: "Not registered with a team. Cannot send messages." }] };
         }
@@ -101,7 +122,7 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
         references: Type.Optional(Type.Array(Type.String({ description: "Relevant task IDs, file paths, or artifact references" }))),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
-        const identity = getIdentity();
+        const identity = await resolveIdentity();
         if (!identity) {
           return { content: [{ type: "text" as const, text: "Not registered with a team." }] };
         }
@@ -158,7 +179,7 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
         references: Type.Optional(Type.Array(Type.String({ description: "Relevant file paths, artifacts, or checks to review" }))),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
-        const identity = getIdentity();
+        const identity = await resolveIdentity();
         if (!identity) {
           return { content: [{ type: "text" as const, text: "Not registered with a team." }] };
         }
@@ -219,7 +240,7 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
         artifacts: Type.Optional(Type.Array(Type.String({ description: "Files, task IDs, or artifacts the next role should inspect first" }))),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
-        const identity = getIdentity();
+        const identity = await resolveIdentity();
         if (!identity) {
           return { content: [{ type: "text" as const, text: "Not registered with a team." }] };
         }
@@ -298,7 +319,7 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
         notes: Type.Optional(Type.String({ description: "Optional extra delivery notes" })),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
-        const identity = getIdentity();
+        const identity = await resolveIdentity();
         if (!identity) {
           return { content: [{ type: "text" as const, text: "Not registered with a team." }] };
         }
@@ -344,6 +365,68 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
         }
       },
     },
+    {
+      name: "teamclaw_request_parallel_help",
+      label: "Request Parallel Help",
+      description: "Ask the controller to spawn more same-role or target-role workers for parallel work on this requirement",
+      parameters: Type.Object({
+        taskId: Type.String({ description: "Current task ID" }),
+        reason: Type.String({ description: "Why this task should be split across more workers now" }),
+        requestedWorkerCount: Type.Optional(Type.Number({ description: "Desired total worker count for this role after expansion" })),
+        targetRole: Type.Optional(Type.String({ description: "Role that should receive more workers; defaults to the current worker role" })),
+        suggestedWorkstreams: Type.Optional(Type.Array(Type.String({ description: "Concrete parallel workstreams or module slices the controller should fan out" }))),
+      }),
+      async execute(_id: string, params: Record<string, unknown>) {
+        const identity = await resolveIdentity();
+        if (!identity) {
+          return { content: [{ type: "text" as const, text: "Not registered with a team." }] };
+        }
+
+        const taskId = String(params.taskId ?? "");
+        const reason = String(params.reason ?? "").trim();
+        const targetRole = typeof params.targetRole === "string" && params.targetRole.trim()
+          ? params.targetRole.trim()
+          : identity.role;
+        const requestedWorkerCount = typeof params.requestedWorkerCount === "number"
+          ? Math.max(2, Math.min(10, Math.floor(params.requestedWorkerCount)))
+          : undefined;
+        const suggestedWorkstreams = Array.isArray(params.suggestedWorkstreams)
+          ? params.suggestedWorkstreams.map((entry) => String(entry ?? "").trim()).filter(Boolean)
+          : [];
+
+        if (!taskId || !reason) {
+          return { content: [{ type: "text" as const, text: "taskId and reason are required." }] };
+        }
+
+        try {
+          const res = await fetch(`${identity.controllerUrl}/api/v1/tasks/${taskId}/parallel-help`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              requestedBy: identity.workerId,
+              requestedByRole: identity.role,
+              targetRole,
+              reason,
+              requestedWorkerCount,
+              suggestedWorkstreams,
+            }),
+          });
+
+          if (!res.ok) {
+            return { content: [{ type: "text" as const, text: `Failed to request parallel help: ${res.status}` }] };
+          }
+
+          return {
+            content: [{
+              type: "text" as const,
+              text: `Parallel help requested for ${taskId}${requestedWorkerCount ? ` (target ${targetRole} workers: ${requestedWorkerCount})` : ""}.`,
+            }],
+          };
+        } catch (err) {
+          return { content: [{ type: "text" as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+        }
+      },
+    },
     {
       name: "teamclaw_request_clarification",
       label: "Request Clarification",
@@ -372,7 +455,7 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
         })),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
-        const identity = getIdentity();
+        const identity = await resolveIdentity();
         if (!identity) {
           return { content: [{ type: "text" as const, text: "Not registered with a team." }] };
         }
@@ -419,7 +502,7 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
       description: "Get current team status including all workers and tasks",
       parameters: Type.Object({}),
       async execute(_id: string) {
-        const identity = getIdentity();
+        const identity = await resolveIdentity();
         if (!identity) {
           return { content: [{ type: "text" as const, text: "Not registered with a team." }] };
         }
@@ -443,6 +526,7 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
       parameters: Type.Object({
         taskId: Type.String({ description: "Task ID" }),
         progress: Type.Optional(Type.String({ description: "Progress update message" })),
+        message: Type.Optional(Type.String({ description: "Alias for progress when the runtime sends a generic message field" })),
         status: Type.Optional(Type.String({ description: "Optional non-terminal status: in_progress or review. Do not use completed or failed here." })),
         summary: Type.Optional(Type.String({ description: "Short structured progress summary" })),
         currentStep: Type.Optional(Type.String({ description: "What the worker is doing right now" })),
@@ -450,19 +534,19 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
         blockers: Type.Optional(Type.Array(Type.String({ description: "Any blockers slowing progress" }))),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
-        const identity = getIdentity();
+        const identity = await resolveIdentity();
         if (!identity) {
           return { content: [{ type: "text" as const, text: "Not registered with a team." }] };
         }
 
         const taskId = String(params.taskId ?? "");
-        const progress = typeof params.progress === "string" ? params.progress : "";
+        const progress = normalizeProgressText(params);
         const status = typeof params.status === "string" ? params.status : undefined;
 
         if (!taskId) {
           return { content: [{ type: "text" as const, text: "taskId is required." }] };
         }
-        if (!progress && typeof params.summary !== "string") {
+        if (!progress) {
           return { content: [{ type: "text" as const, text: "progress or summary is required." }] };
         }
         if (status && !ALLOWED_PROGRESS_STATUSES.has(status)) {