@teamclaws/teamclaw 2026.3.24-5 → 2026.3.24-7

package/cli.mjs

@@ -3,6 +3,7 @@
 import { spawnSync } from "node:child_process";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
+import http from "node:http";
 import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
@@ -25,7 +26,7 @@ const DEFAULT_TEAM_NAME = "default";
 const DEFAULT_TASK_TIMEOUT_MS = 1_800_000;
 const DEFAULT_AGENT_TIMEOUT_SECONDS = 2_400;
 const DEFAULT_LOCAL_ROLES = ["architect", "developer", "qa"];
-const DEFAULT_PROVISIONING_ROLES = ["architect", "developer", "qa"];
+const LEGACY_DEFAULT_PROVISIONING_ROLES = ["architect", "developer", "qa"];
 
 const ROLE_OPTIONS = [
   { value: "pm", label: "Product Manager" },
@@ -189,6 +190,30 @@ function resolveDefaultOpenClawWorkspaceDir(env = process.env) {
   return path.join(resolveDefaultOpenClawStateDir(env), "workspace");
 }
 
+function resolveOpenClawStateDirForConfigPath(configPath) {
+  return path.dirname(path.resolve(configPath));
+}
+
+function resolveOpenClawWorkspaceDirForConfigPath(configPath) {
+  return path.join(resolveOpenClawStateDirForConfigPath(configPath), "workspace");
+}
+
+function sanitizeInstallerPathSegment(value) {
+  const normalized = String(value || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || "default";
+}
+
+function resolveDefaultTeamClawWorkspaceDir(configPath, teamName) {
+  return path.join(
+    resolveOpenClawStateDirForConfigPath(configPath),
+    "teamclaw-workspaces",
+    sanitizeInstallerPathSegment(teamName),
+  );
+}
+
 async function pathExists(targetPath) {
   try {
     await fs.access(targetPath);
@@ -309,10 +334,40 @@ function getCurrentWorkspacePath(config) {
   return typeof defaults.workspace === "string" ? expandUserPath(defaults.workspace) : "";
 }
 
+function resolveInstallerWorkspaceDefault(configPath, config, teamName) {
+  const currentWorkspacePath = getCurrentWorkspacePath(config);
+  const sharedWorkspacePath = resolveOpenClawWorkspaceDirForConfigPath(configPath);
+  if (currentWorkspacePath && path.resolve(currentWorkspacePath) !== path.resolve(sharedWorkspacePath)) {
+    return currentWorkspacePath;
+  }
+  return resolveDefaultTeamClawWorkspaceDir(configPath, teamName);
+}
+
 function dedupeStrings(values) {
   return Array.from(new Set(values.filter((value) => typeof value === "string" && value.trim()).map((value) => value.trim())));
 }
 
+function hasSameStringSet(left, right) {
+  const normalizedLeft = dedupeStrings(left).slice().sort();
+  const normalizedRight = dedupeStrings(right).slice().sort();
+  if (normalizedLeft.length !== normalizedRight.length) {
+    return false;
+  }
+  return normalizedLeft.every((value, index) => value === normalizedRight[index]);
+}
+
+function normalizeConfiguredRoleList(raw) {
+  return Array.isArray(raw) ? dedupeStrings(raw) : [];
+}
+
+function resolveDefaultProvisioningRoles(existingTeamClaw) {
+  const existingRoles = normalizeConfiguredRoleList(existingTeamClaw.workerProvisioningRoles);
+  if (existingRoles.length === 0) {
+    return [];
+  }
+  return hasSameStringSet(existingRoles, LEGACY_DEFAULT_PROVISIONING_ROLES) ? [] : existingRoles;
+}
+
 function extractModelOptions(config) {
   const currentModel = getCurrentModel(config);
   const models = [];
@@ -519,6 +574,28 @@ async function promptRoleList(prompter, message, defaultRoles) {
   return parseRoleList(raw).values;
 }
 
+async function promptOptionalRoleList(prompter, message, defaultRoles) {
+  const defaultValue = defaultRoles.join(",");
+  if (!prompter.yes) {
+    console.log(
+      `Available roles: ${ROLE_OPTIONS.map((option) => `${option.value} (${option.label})`).join(", ")}. Leave empty to allow all roles.`,
+    );
+  }
+  const raw = await prompter.text({
+    message,
+    defaultValue,
+    allowEmpty: true,
+    validate: (value) => {
+      const parsed = parseRoleList(value);
+      if (parsed.invalid.length > 0) {
+        return `Unknown role ids: ${parsed.invalid.join(", ")}`;
+      }
+      return "";
+    },
+  });
+  return parseRoleList(raw).values;
+}
+
 function buildStartCommand(configPath) {
   const defaultPath = resolveDefaultOpenClawConfigPath();
   if (path.resolve(configPath) === path.resolve(defaultPath)) {
@@ -534,6 +611,57 @@ function shellEscape(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+function isControllerInstallMode(installMode) {
+  return installMode !== "worker";
+}
+
+function isOnDemandControllerInstallMode(installMode) {
+  return installMode === "controller-process" || installMode === "controller-docker" || installMode === "controller-kubernetes";
+}
+
+function describeProvisioningRoles(roles) {
+  return Array.isArray(roles) && roles.length > 0
+    ? roles.join(", ")
+    : "all TeamClaw roles (controller decides at runtime)";
+}
+
+function getLocalUiUrl(port) {
+  return `http://127.0.0.1:${port}/ui`;
+}
+
+function rankLanAddress(address) {
+  if (address.startsWith("192.168.")) {
+    return 0;
+  }
+  if (address.startsWith("10.")) {
+    return 1;
+  }
+  const parts = address.split(".").map((value) => Number.parseInt(value, 10));
+  if (parts.length === 4 && parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) {
+    return 2;
+  }
+  return 3;
+}
+
+function listLanUiUrls(port) {
+  const urls = [];
+  const interfaces = os.networkInterfaces();
+  for (const records of Object.values(interfaces)) {
+    for (const record of records ?? []) {
+      if (!record || record.internal || record.family !== "IPv4") {
+        continue;
+      }
+      urls.push({
+        address: record.address,
+        url: `http://${record.address}:${port}/ui`,
+      });
+    }
+  }
+  return urls
+    .sort((left, right) => rankLanAddress(left.address) - rankLanAddress(right.address) || left.address.localeCompare(right.address))
+    .map((entry) => entry.url);
+}
+
 function installPluginWithCommand(command, args, env) {
   const result = spawnSync(command, args, {
     stdio: "inherit",
@@ -546,6 +674,50 @@ function installPluginWithCommand(command, args, env) {
   };
 }
 
+function runGatewayCommand(command, args, env) {
+  const result = spawnSync(command, args, {
+    env,
+    encoding: "utf8",
+  });
+  return {
+    status: result.status ?? 1,
+    signal: result.signal ?? null,
+    error: result.error ?? null,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+function readJsonIfExists(filePath) {
+  try {
+    if (!fsSync.existsSync(filePath)) {
+      return null;
+    }
+    return JSON.parse(fsSync.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function inspectInstalledPlugin(configPath) {
+  const stateDir = path.dirname(path.resolve(configPath));
+  const pluginDir = path.join(stateDir, "extensions", PLUGIN_ID);
+  if (!fsSync.existsSync(pluginDir)) {
+    return null;
+  }
+  const manifest = readJsonIfExists(path.join(pluginDir, "openclaw.plugin.json"));
+  const packageJson = readJsonIfExists(path.join(pluginDir, "package.json"));
+  const version = typeof manifest?.version === "string" && manifest.version.trim()
+    ? manifest.version.trim()
+    : typeof packageJson?.version === "string" && packageJson.version.trim()
+      ? packageJson.version.trim()
+      : "";
+  return {
+    pluginDir,
+    version: version || null,
+  };
+}
+
 function createPackageTarball(env) {
   let tempDir = "";
   try {
@@ -591,11 +763,82 @@ function createPackageTarball(env) {
   }
 }
 
+function attemptPluginUninstall({ configPath }) {
+  const env = {
+    ...process.env,
+    OPENCLAW_CONFIG_PATH: configPath,
+  };
+  const candidates = [
+    {
+      label: "openclaw",
+      command: "openclaw",
+      args: ["plugins", "uninstall", PLUGIN_ID, "--force"],
+    },
+    {
+      label: "npm exec fallback",
+      command: "npm",
+      args: ["exec", "-y", "openclaw@latest", "--", "plugins", "uninstall", PLUGIN_ID, "--force"],
+    },
+  ];
+  const failures = [];
+  for (let index = 0; index < candidates.length; index += 1) {
+    const candidate = candidates[index];
+    console.log(`\nRemoving existing ${PLUGIN_ID} plugin with ${candidate.label}...`);
+    const result = installPluginWithCommand(candidate.command, candidate.args, env);
+    if (result.status === 0 && !result.error) {
+      return {
+        ok: true,
+        method: candidate.label,
+      };
+    }
+    const errorCode = result.error && typeof result.error === "object" ? result.error.code : "";
+    const detail = result.error
+      ? result.error.message
+      : result.signal
+        ? `terminated by signal ${result.signal}`
+        : `exited with code ${result.status}`;
+    failures.push(`${candidate.label} failed: ${detail}`);
+    if (errorCode === "ENOENT" && index < candidates.length - 1) {
+      console.log(`${candidate.command} was not found. Trying the next uninstall fallback...`);
+      continue;
+    }
+    break;
+  }
+  return {
+    ok: false,
+    error: failures.join("; "),
+  };
+}
+
 function attemptPluginInstall({ configPath }) {
   const env = {
     ...process.env,
     OPENCLAW_CONFIG_PATH: configPath,
   };
+  const installedPlugin = inspectInstalledPlugin(configPath);
+  if (installedPlugin?.version === PACKAGE_VERSION) {
+    console.log(
+      `\nFound existing TeamClaw plugin at ${installedPlugin.pluginDir} (version ${installedPlugin.version}). Skipping plugin reinstall.`,
+    );
+    return {
+      ok: true,
+      method: `already installed (${installedPlugin.version})`,
+      skipped: true,
+    };
+  }
+  if (installedPlugin) {
+    const installedVersion = installedPlugin.version ? `version ${installedPlugin.version}` : "an unknown version";
+    console.log(
+      `\nFound existing TeamClaw plugin at ${installedPlugin.pluginDir} (${installedVersion}). Removing it before install...`,
+    );
+    const uninstallResult = attemptPluginUninstall({ configPath });
+    if (!uninstallResult.ok) {
+      return {
+        ok: false,
+        error: `Could not remove existing TeamClaw plugin at ${installedPlugin.pluginDir}: ${uninstallResult.error}`,
+      };
+    }
+  }
   const candidates = [];
   const tarballResult = createPackageTarball(env);
   if (tarballResult.ok) {
@@ -674,10 +917,127 @@ function attemptPluginInstall({ configPath }) {
   }
 }
 
-async function collectInstallChoices(config, prompter) {
+function attemptGatewayRestart({ configPath }) {
+  const env = {
+    ...process.env,
+    OPENCLAW_CONFIG_PATH: configPath,
+  };
+  const candidates = [
+    {
+      label: "openclaw",
+      command: "openclaw",
+      args: ["gateway", "restart"],
+    },
+    {
+      label: "npm exec fallback",
+      command: "npm",
+      args: ["exec", "-y", "openclaw@latest", "--", "gateway", "restart"],
+    },
+  ];
+  const failures = [];
+  for (let index = 0; index < candidates.length; index += 1) {
+    const candidate = candidates[index];
+    const result = runGatewayCommand(candidate.command, candidate.args, env);
+    if (result.status === 0 && !result.error) {
+      return {
+        ok: true,
+        method: candidate.label,
+      };
+    }
+    const detail = result.error
+      ? result.error.message
+      : (result.stderr || result.stdout || (result.signal
+          ? `terminated by signal ${result.signal}`
+          : `exited with code ${result.status}`)).trim();
+    failures.push(`${candidate.label} failed: ${detail}`);
+    const errorCode = result.error && typeof result.error === "object" ? result.error.code : "";
+    if (!(errorCode === "ENOENT" && index < candidates.length - 1)) {
+      break;
+    }
+  }
+  return {
+    ok: false,
+    error: failures.join("; "),
+  };
+}
+
+async function waitForControllerHealth(port) {
+  const url = `http://127.0.0.1:${port}/api/v1/health`;
+  const deadline = Date.now() + 30_000;
+  let lastError = "";
+  while (Date.now() < deadline) {
+    try {
+      const response = await new Promise((resolve, reject) => {
+        const request = http.get(
+          url,
+          {
+            agent: false,
+            headers: {
+              Connection: "close",
+            },
+          },
+          (incoming) => {
+            let body = "";
+            incoming.setEncoding("utf8");
+            incoming.on("data", (chunk) => {
+              body += chunk;
+            });
+            incoming.on("end", () => {
+              resolve({
+                statusCode: incoming.statusCode ?? 0,
+                body,
+              });
+            });
+          },
+        );
+        request.setTimeout(5_000, () => {
+          request.destroy(new Error("request timed out"));
+        });
+        request.on("error", reject);
+      });
+      if (response.statusCode >= 200 && response.statusCode < 300) {
+        const payload = JSON.parse(response.body);
+        if (payload && payload.status === "ok" && payload.mode === "controller") {
+          return {
+            ok: true,
+            url,
+          };
+        }
+        lastError = "unexpected health payload";
+      } else {
+        lastError = `HTTP ${response.statusCode}`;
+      }
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1_000));
+  }
+  return {
+    ok: false,
+    url,
+    error: lastError || "timed out after 30s",
+  };
+}
+
+async function collectInstallChoices(configPath, config, prompter) {
   const existingTeamClaw = getExistingTeamClawConfig(config);
   const existingMode = typeof existingTeamClaw.mode === "string" ? existingTeamClaw.mode.trim() : "";
-  const modeDefault = existingMode === "worker" ? "worker" : "single-local";
+  const existingProvisioningType =
+    typeof existingTeamClaw.workerProvisioningType === "string" ? existingTeamClaw.workerProvisioningType.trim() : "";
+  let modeDefault = "single-local";
+  if (existingMode === "worker") {
+    modeDefault = "worker";
+  } else if (existingMode === "controller") {
+    if (existingProvisioningType === "docker") {
+      modeDefault = "controller-docker";
+    } else if (existingProvisioningType === "kubernetes") {
+      modeDefault = "controller-kubernetes";
+    } else if (existingProvisioningType === "process") {
+      modeDefault = "controller-process";
+    } else if (!Array.isArray(existingTeamClaw.localRoles) || existingTeamClaw.localRoles.length === 0) {
+      modeDefault = "controller-manual";
+    }
+  }
 
   const installMode = await prompter.select({
     message: "Choose an installation mode",
@@ -710,7 +1070,7 @@ async function collectInstallChoices(config, prompter) {
   });
   const workspacePath = expandUserPath(await prompter.text({
     message: "OpenClaw workspace directory",
-    defaultValue: getCurrentWorkspacePath(config) || resolveDefaultOpenClawWorkspaceDir(),
+    defaultValue: resolveInstallerWorkspaceDefault(configPath, config, teamName),
   }));
 
   if (installMode === "worker") {
@@ -790,12 +1150,10 @@ async function collectInstallChoices(config, prompter) {
     };
   }
 
-  const provisioningRoles = await promptRoleList(
+  const provisioningRoles = await promptOptionalRoleList(
     prompter,
-    "On-demand roles to launch (comma-separated)",
-    Array.isArray(existingTeamClaw.workerProvisioningRoles) && existingTeamClaw.workerProvisioningRoles.length > 0
-      ? existingTeamClaw.workerProvisioningRoles
-      : DEFAULT_PROVISIONING_ROLES,
+    "On-demand roles to allow (comma-separated, leave empty for all roles)",
+    resolveDefaultProvisioningRoles(existingTeamClaw),
   );
   const maxPerRole = await prompter.number({
     message: "Maximum on-demand workers per role",
@@ -838,11 +1196,11 @@ async function collectInstallChoices(config, prompter) {
           : DEFAULT_TEAMCLAW_IMAGE,
     });
     const dockerWorkspaceVolume = await prompter.text({
-      message: "Docker workspace volume or host path (leave empty for ephemeral workspaces)",
+      message: "Docker workspace volume or host path (leave empty for isolated ephemeral workspaces)",
       defaultValue:
         typeof existingTeamClaw.workerProvisioningDockerWorkspaceVolume === "string"
           ? existingTeamClaw.workerProvisioningDockerWorkspaceVolume.trim()
-          : "teamclaw-workspaces",
+          : "",
       allowEmpty: true,
     });
     return {
@@ -893,7 +1251,7 @@ async function collectInstallChoices(config, prompter) {
         : "teamclaw-worker",
   });
   const kubernetesWorkspacePersistentVolumeClaim = await prompter.text({
-    message: "Kubernetes workspace PVC (leave empty for ephemeral workspaces)",
+    message: "Kubernetes workspace PVC (leave empty for isolated ephemeral workspaces)",
     defaultValue:
       typeof existingTeamClaw.workerProvisioningKubernetesWorkspacePersistentVolumeClaim === "string"
         ? existingTeamClaw.workerProvisioningKubernetesWorkspacePersistentVolumeClaim.trim()
@@ -1133,19 +1491,38 @@ function buildSummaryLines(params) {
   }
   if (params.pluginInstallStatus === "installed") {
     lines.push(`Plugin install: completed via ${params.pluginInstallMethod}`);
+  } else if (params.pluginInstallStatus === "already-installed") {
+    lines.push(`Plugin install: ${params.pluginInstallMethod}`);
   } else if (params.pluginInstallStatus === "skipped") {
     lines.push("Plugin install: skipped");
   } else if (params.pluginInstallError) {
     lines.push(`Plugin install: ${params.pluginInstallError}`);
   }
+  if (params.gatewayRestartStatus === "restarted") {
+    lines.push(`Gateway restart: completed via ${params.gatewayRestartMethod}`);
+  } else if (params.gatewayRestartStatus === "failed") {
+    lines.push(`Gateway restart: ${params.gatewayRestartError}`);
+  }
+  if (params.controllerHealthStatus === "ok") {
+    lines.push(`Controller health: ok (${params.controllerHealthUrl})`);
+  } else if (params.controllerHealthStatus === "failed") {
+    lines.push(`Controller health: ${params.controllerHealthError} (${params.controllerHealthUrl})`);
+  }
   lines.push(`Start command: ${buildStartCommand(params.configPath)}`);
 
-  if (params.choices.installMode === "single-local") {
-    lines.push(`Open UI: http://127.0.0.1:${params.choices.controllerPort}/ui`);
+  if (isControllerInstallMode(params.choices.installMode)) {
+    const lanUiUrls = listLanUiUrls(params.choices.controllerPort);
+    if (lanUiUrls.length > 0) {
+      lines.push(`Open UI (LAN): ${lanUiUrls[0]}`);
+    }
+    lines.push(`Open UI (local): ${getLocalUiUrl(params.choices.controllerPort)}`);
   }
   if (params.choices.installMode === "controller-docker" || params.choices.installMode === "controller-kubernetes") {
     lines.push(`Provisioning image: ${params.choices.workerImage}`);
   }
+  if (isOnDemandControllerInstallMode(params.choices.installMode)) {
+    lines.push(`On-demand roles: ${describeProvisioningRoles(params.choices.provisioningRoles)}`);
+  }
   if (params.choices.installMode === "controller-docker" && params.choices.dockerWorkspaceVolume) {
     lines.push(`Docker workspace volume: ${params.choices.dockerWorkspaceVolume}`);
   }
@@ -1197,7 +1574,7 @@ async function runInstall(options) {
     if (!options.skipPluginInstall && !options.dryRun) {
       const installResult = attemptPluginInstall({ configPath });
       if (installResult.ok) {
-        pluginInstallStatus = "installed";
+        pluginInstallStatus = installResult.skipped ? "already-installed" : "installed";
         pluginInstallMethod = installResult.method;
       } else {
         pluginInstallStatus = "failed";
@@ -1214,7 +1591,7 @@ async function runInstall(options) {
     }
 
     const config = await readOpenClawConfig(configPath);
-    const choices = await collectInstallChoices(config, prompter);
+    const choices = await collectInstallChoices(configPath, config, prompter);
     const nextConfig = applyInstallerChoices(config, choices);
 
     if (options.dryRun) {
@@ -1223,6 +1600,29 @@ async function runInstall(options) {
       await writeConfig(configPath, nextConfig);
     }
 
+    let gatewayRestartStatus = "skipped";
+    let gatewayRestartMethod = "";
+    let gatewayRestartError = "";
+    let controllerHealthStatus = "skipped";
+    let controllerHealthUrl = "";
+    let controllerHealthError = "";
+    if (!options.dryRun) {
+      const restartResult = attemptGatewayRestart({ configPath });
+      if (restartResult.ok) {
+        gatewayRestartStatus = "restarted";
+        gatewayRestartMethod = restartResult.method;
+        if (isControllerInstallMode(choices.installMode)) {
+          const healthResult = await waitForControllerHealth(choices.controllerPort);
+          controllerHealthStatus = healthResult.ok ? "ok" : "failed";
+          controllerHealthUrl = healthResult.url;
+          controllerHealthError = healthResult.error ?? "";
+        }
+      } else {
+        gatewayRestartStatus = "failed";
+        gatewayRestartError = restartResult.error;
+      }
+    }
+
     const summaryLines = buildSummaryLines({
       configPath,
       choices,
@@ -1230,6 +1630,12 @@ async function runInstall(options) {
       pluginInstallStatus,
       pluginInstallMethod,
       pluginInstallError,
+      gatewayRestartStatus,
+      gatewayRestartMethod,
+      gatewayRestartError,
+      controllerHealthStatus,
+      controllerHealthUrl,
+      controllerHealthError,
     });
 
     prompter.note("\nTeamClaw installer summary");

package/index.ts

@@ -1,6 +1,6 @@
 import { definePluginEntry, type OpenClawPluginApi } from "./api.js";
 import { parsePluginConfig } from "./src/types.js";
-import type { TaskExecutionEventInput, WorkerIdentity } from "./src/types.js";
+import type { TaskExecutionEventInput, TeamState, WorkerIdentity } from "./src/types.js";
 import { buildConfigSchema } from "./src/config.js";
 import { loadTeamState } from "./src/state.js";
 import { createRoleTaskExecutor } from "./src/task-executor.js";
@@ -39,9 +39,18 @@ function registerController(api: OpenClawPluginApi, config: ReturnType<typeof pa
     logger,
     runtime: api.runtime,
   });
+  let getControllerTeamState = (): TeamState | null => null;
 
   // Service (starts HTTP server + mDNS + WebSocket)
-  api.registerService(createControllerService({ config, logger, runtime: api.runtime, localWorkerManager }));
+  api.registerService(createControllerService({
+    config,
+    logger,
+    runtime: api.runtime,
+    localWorkerManager,
+    onTeamStateAvailable: (getter) => {
+      getControllerTeamState = getter;
+    },
+  }));
 
   // Prompt injection
   api.on("before_prompt_build", async (_event: unknown, ctx: { sessionKey?: string | null }) => {
@@ -56,7 +65,7 @@ function registerController(api: OpenClawPluginApi, config: ReturnType<typeof pa
       return injector() ?? {};
     }
 
-    const state = await loadTeamState(config.teamName);
+    const state = getControllerTeamState() ?? await loadTeamState(config.teamName);
     const injector = createControllerPromptInjector({
       config,
       getTeamState: () => state,
@@ -78,7 +87,7 @@ function registerController(api: OpenClawPluginApi, config: ReturnType<typeof pa
     return createControllerTools({
       config,
       controllerUrl,
-      getTeamState: () => null,
+      getTeamState: getControllerTeamState,
     });
   });
 }

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "teamclaw",
   "name": "TeamClaw",
   "description": "Virtual team collaboration - multiple OpenClaw instances form a virtual software company with role-based task routing.",
-  "version": "2026.3.24-5",
+  "version": "2026.3.24-7",
   "uiHints": {
     "mode": {
       "label": "Mode",

package/package.json

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

package/src/controller/controller-capacity.ts

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

package/src/controller/controller-service.ts

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

package/src/controller/controller-tools.ts

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { PluginConfig, TaskInfo, TeamState } from "../types.js";
+import { buildControllerNoWorkersMessage, hasOnDemandWorkerProvisioning, shouldBlockControllerWithoutWorkers } from "./controller-capacity.js";
 
 export type ControllerToolsDeps = {
   config: PluginConfig;
@@ -46,6 +47,16 @@ export function createControllerTools(deps: ControllerToolsDeps) {
           return { content: [{ type: "text" as const, text: "title is required." }] };
         }
 
+        const state = getTeamState();
+        if (shouldBlockControllerWithoutWorkers(config, state)) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: `${buildControllerNoWorkersMessage()} Stop after reporting this block to the human.`,
+            }],
+          };
+        }
+
         const blocker = detectExecutionReadyBlocker(description);
         if (blocker) {
           return {
@@ -80,7 +91,9 @@ export function createControllerTools(deps: ControllerToolsDeps) {
           const assigned = task.assignedWorkerId
             ? ` -> assigned to ${task.assignedWorkerId}`
             : task.status === "pending"
-              ? " (pending - no available worker)"
+              ? hasOnDemandWorkerProvisioning(config)
+                ? " (pending - waiting for worker provisioning or an available worker)"
+                : " (pending - no registered/available worker)"
               : "";
           const recommended = Array.isArray(task.recommendedSkills) && task.recommendedSkills.length > 0
             ? ` | skills: ${task.recommendedSkills.join(", ")}`

package/src/controller/http-server.ts

@@ -38,6 +38,8 @@ import { TaskRouter } from "./task-router.js";
 import { MessageRouter } from "./message-router.js";
 import { TeamWebSocketServer } from "./websocket.js";
 import type { WorkerProvisioningManager } from "./worker-provisioning.js";
+import { createControllerPromptInjector } from "./prompt-injector.js";
+import { buildControllerNoWorkersMessage, shouldBlockControllerWithoutWorkers } from "./controller-capacity.js";
 
 export type ControllerHttpDeps = {
   config: PluginConfig;
@@ -59,6 +61,16 @@ const MAX_TASK_CONTEXT_SUMMARY_CHARS = 500;
 const CONTROLLER_INTAKE_TIMEOUT_CAP_MS = 180_000;
 const CONTROLLER_INTAKE_SESSION_PREFIX = "teamclaw-controller-web:";
 
+export function buildControllerIntakeSystemPrompt(
+  deps: Pick<ControllerHttpDeps, "config" | "getTeamState">,
+): string {
+  const injector = createControllerPromptInjector({
+    config: deps.config,
+    getTeamState: deps.getTeamState,
+  });
+  return injector()?.prependSystemContext ?? "";
+}
+
 function mapTaskStatusToExecutionStatus(taskStatus: TaskStatus, current?: TaskExecution["status"]): TaskExecution["status"] {
   switch (taskStatus) {
     case "completed":
@@ -524,6 +536,7 @@ async function runControllerIntake(
   const runResult = await deps.runtime.subagent.run({
     sessionKey,
     message,
+    extraSystemPrompt: buildControllerIntakeSystemPrompt(deps),
     idempotencyKey: `controller-intake-${generateId()}`,
   });
   recordControllerRunEvent(controllerRun.id, {
@@ -1241,6 +1254,13 @@ async function handleRequest(
   const requestUrl = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
 
   // ==================== Web UI ====================
+  if (req.method === "GET" && pathname === "/") {
+    res.statusCode = 302;
+    res.setHeader("Location", "/ui");
+    res.end();
+    return;
+  }
+
   if (req.method === "GET" && (pathname === "/ui" || pathname === "/ui/")) {
     const uiPath = path.join(import.meta.dirname, "..", "ui");
     serveStaticFile(res, path.join(uiPath, "index.html"), "text/html; charset=utf-8");
@@ -1456,6 +1476,10 @@ async function handleRequest(
       sendError(res, 400, "title is required");
       return;
     }
+    if (createdBy === "controller" && shouldBlockControllerWithoutWorkers(deps.config, getTeamState())) {
+      sendError(res, 409, buildControllerNoWorkersMessage());
+      return;
+    }
 
     const taskId = generateId();
     const now = Date.now();

package/src/controller/prompt-injector.ts

@@ -1,5 +1,6 @@
 import type { PluginConfig, TeamState } from "../types.js";
 import { ROLES } from "../roles.js";
+import { hasOnDemandWorkerProvisioning, shouldBlockControllerWithoutWorkers } from "./controller-capacity.js";
 
 const TEAMCLAW_ROLE_IDS_TEXT = [
   "pm",
@@ -22,15 +23,13 @@ export type ControllerPromptDeps = {
 export function createControllerPromptInjector(deps: ControllerPromptDeps) {
   return () => {
     const state = deps.getTeamState();
-    if (!state) return null;
-
-    const workers = Object.values(state.workers);
-    const tasks = Object.values(state.tasks);
+    const workers = Object.values(state?.workers ?? {});
+    const tasks = Object.values(state?.tasks ?? {});
     const pendingTasks = tasks.filter((t) => t.status === "pending");
     const activeTasks = tasks.filter((t) => t.status === "in_progress" || t.status === "assigned");
     const blockedTasks = tasks.filter((t) => t.status === "blocked");
     const completedTasks = tasks.filter((t) => t.status === "completed");
-    const pendingClarifications = Object.values(state.clarifications).filter((c) => c.status === "pending");
+    const pendingClarifications = Object.values(state?.clarifications ?? {}).filter((c) => c.status === "pending");
 
     const parts: string[] = [
       "## TeamClaw Controller Mode",
@@ -46,8 +45,17 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
       "### Current Team Status",
     ];
 
-    if (workers.length === 0) {
-      parts.push("- No workers registered yet");
+    if (!state) {
+      parts.push("- Team state is not loaded yet; treat this as a fresh controller intake and establish execution-ready tasks from the human requirement.");
+    } else if (workers.length === 0) {
+      if (shouldBlockControllerWithoutWorkers(deps.config, state)) {
+        parts.push("- No workers are registered and on-demand provisioning is disabled.");
+        parts.push("- Blocking rule: you may analyze the requirement and identify the needed roles, but do not create TeamClaw tasks yet.");
+        parts.push("- Do not start doing the worker-role work yourself. Tell the human to bring workers online or enable process/docker/kubernetes provisioning first.");
+      } else {
+        parts.push("- No workers are registered yet, but on-demand provisioning is enabled.");
+        parts.push("- You may still create execution-ready TeamClaw tasks for the required roles; the controller will provision workers on demand.");
+      }
     } else {
       for (const w of workers) {
         const roleDef = ROLES.find((r) => r.id === w.role);
@@ -86,6 +94,13 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
       parts.push(`- ${role.icon} ${role.label}: ${role.description}.${skillLine}`);
     }
 
+    parts.push("");
+    parts.push("## Controller Workflow");
+    parts.push("- First determine which TeamClaw roles are needed for the human requirement.");
+    parts.push("- Then translate the requirement into the minimum execution-ready TeamClaw tasks owned by those roles.");
+    parts.push("- TeamClaw workers, not the controller, do the specialist work in the shared repo/workspace.");
+    parts.push("- After workers report progress, results, or handoffs, create only the next tasks whose prerequisites are now satisfied.");
+
     parts.push("");
     parts.push("## Requirement Intake Rules");
     parts.push("- Human messages are the initial requirement, not an already-decomposed task tree.");
@@ -111,6 +126,13 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
     parts.push("- Do not let a worker task turn itself into a controller/coordinator workflow.");
     parts.push("- If the correct role is busy, prefer waiting, messaging, or explicit reassignment over routing core work to an unrelated role.");
     parts.push("- If a task is blocked by missing information, keep it in the clarification queue until the human answers; do not guess on the user's behalf.");
+    parts.push("- You are never a substitute worker. Do not personally perform architecture, implementation, QA, release, infra, design, marketing, research, or other specialist work.");
+    parts.push("- Your own reply must stay at the orchestration layer: clarification, role selection, task decomposition, assignment decisions, and concise status updates.");
+    if (hasOnDemandWorkerProvisioning(deps.config)) {
+      parts.push("- If no workers are currently registered but on-demand provisioning is enabled, you may still create execution-ready tasks so the required roles can be provisioned.");
+    } else {
+      parts.push("- If no workers are registered, you may mention which roles would be needed, but stop there and report the worker-capacity block to the human.");
+    }
     parts.push("- Use the controller itself for requirement analysis; use the PM role only for PM-owned deliverables after intake is clear.");
     parts.push(`- Use exact TeamClaw role IDs only: ${TEAMCLAW_ROLE_IDS_TEXT}.`);