@teamclaws/teamclaw 2026.3.26-2 → 2026.4.2-2

package/src/networking.ts

@@ -0,0 +1,99 @@
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+
+function isPrivateLanIpv4(address: string): boolean {
+  if (address.startsWith("10.") || address.startsWith("192.168.")) {
+    return true;
+  }
+  const parts = address.split(".").map((value) => Number.parseInt(value, 10));
+  return parts.length === 4 && parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31;
+}
+
+function rankLanAddress(address: string): number {
+  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 parseDefaultRouteInterface(text: string): string {
+  const directMatch = text.match(/(?:^|\n)\s*interface:\s*(\S+)/i);
+  if (directMatch?.[1]) {
+    return directMatch[1];
+  }
+  const devMatch = text.match(/(?:^|\n)default(?:\s+via\s+\S+)?\s+dev\s+(\S+)/i);
+  if (devMatch?.[1]) {
+    return devMatch[1];
+  }
+  return "";
+}
+
+function probeDefaultRouteInterface(): string {
+  const candidates: Array<{ command: string; args: string[] }> = process.platform === "darwin"
+    ? [
+        { command: "route", args: ["-n", "get", "default"] },
+        { command: "ip", args: ["route", "show", "default"] },
+      ]
+    : [
+        { command: "ip", args: ["route", "show", "default"] },
+        { command: "route", args: ["-n", "get", "default"] },
+      ];
+  for (const candidate of candidates) {
+    const result = spawnSync(candidate.command, candidate.args, { encoding: "utf8" });
+    if (result.status !== 0 || result.error) {
+      continue;
+    }
+    const interfaceName = parseDefaultRouteInterface(result.stdout || "");
+    if (interfaceName) {
+      return interfaceName;
+    }
+  }
+  return "";
+}
+
+function listNonInternalIpv4Addresses(): string[] {
+  const addresses: 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;
+      }
+      addresses.push(record.address);
+    }
+  }
+  return addresses.filter((value, index, values) => values.indexOf(value) === index);
+}
+
+export function resolvePreferredLanAddress(): string | null {
+  const interfaces = os.networkInterfaces();
+  const defaultRouteInterface = probeDefaultRouteInterface();
+  if (defaultRouteInterface) {
+    const records = (interfaces[defaultRouteInterface] ?? [])
+      .filter((record): record is os.NetworkInterfaceInfoIPv4 => Boolean(record) && record.family === "IPv4" && !record.internal);
+    const preferredPrivate = records.find((record) => isPrivateLanIpv4(record.address));
+    if (preferredPrivate) {
+      return preferredPrivate.address;
+    }
+    if (records[0]) {
+      return records[0].address;
+    }
+  }
+
+  const privateCandidates = listNonInternalIpv4Addresses()
+    .filter((address) => isPrivateLanIpv4(address))
+    .sort((left, right) => rankLanAddress(left) - rankLanAddress(right) || left.localeCompare(right));
+  if (privateCandidates[0]) {
+    return privateCandidates[0];
+  }
+
+  const fallback = listNonInternalIpv4Addresses()[0];
+  return fallback || null;
+}

package/src/openclaw-workspace.ts

@@ -1,10 +1,16 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import JSON5 from "json5";
 import type { PluginLogger } from "../api.js";
 
+export const TEAMCLAW_AGENT_ID = "teamclaw";
+export const TEAMCLAW_ISOLATION_MODE_INDEPENDENT = "independent";
+export const TEAMCLAW_ISOLATION_MODE_MAIN = "main";
+const TEAMCLAW_RECOMMENDED_EXEC_SECURITY = "full";
+const TEAMCLAW_RECOMMENDED_EXEC_ASK = "off";
+
 const DEFAULT_AGENTS_MD = `# AGENTS.md
 
 This workspace is shared by TeamClaw controller and workers.
@@ -12,6 +18,8 @@ This workspace is shared by TeamClaw controller and workers.
 Rules:
 - Treat task-provided file paths as hints; verify they exist before reading or editing.
 - Use the shared \`memory/\` directory for lightweight notes when useful.
+- Check \`memory/patterns.md\` for previously discovered codebase patterns before starting work.
+- Check for \`.teamclaw-notes.md\` files in directories you work on for prior context.
 - Report meaningful progress during longer tasks.
 - If requirements or environment details are missing and work cannot continue safely, request clarification instead of guessing.
 `;
@@ -31,10 +39,25 @@ const DEFAULT_HEARTBEAT_MD = `# HEARTBEAT.md
 # Keep this file empty (or with only comments) to skip heartbeat API calls.
 `;
 
+const DEFAULT_PATTERNS_MD = `# Codebase Patterns
+
+Reusable patterns discovered by TeamClaw workers during task execution.
+This file is automatically maintained — new patterns are appended as workers complete tasks.
+Read this file before starting work to benefit from previously discovered knowledge.
+`;
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+function normalizeAgentId(value: unknown): string {
+  const trimmed = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (!trimmed) {
+    return "main";
+  }
+  return trimmed.replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "main";
+}
+
 function expandUserPath(
   value: string,
   homedir: () => string = os.homedir,
@@ -56,24 +79,139 @@ function resolveConfiguredOpenClawWorkspaceDir(
   env: NodeJS.ProcessEnv = process.env,
   homedir: () => string = os.homedir,
 ): string {
+  const parsed = loadOpenClawConfigRecord(env, homedir);
+  if (!parsed) {
+    return "";
+  }
+  const agents = isRecord(parsed.agents) ? parsed.agents : null;
+  const defaults = agents && isRecord(agents.defaults) ? agents.defaults : null;
+  if (defaults && typeof defaults.workspace === "string" && defaults.workspace.trim()) {
+    return expandUserPath(defaults.workspace, homedir);
+  }
+  return "";
+}
+
+function resolveConfiguredTeamClawIsolationMode(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const parsed = loadOpenClawConfigRecord(env, homedir);
+  if (!parsed) {
+    return TEAMCLAW_ISOLATION_MODE_INDEPENDENT;
+  }
+  const plugins = isRecord(parsed.plugins) ? parsed.plugins : null;
+  const entries = plugins && isRecord(plugins.entries) ? plugins.entries : null;
+  const teamclawEntry = entries && isRecord(entries[TEAMCLAW_AGENT_ID]) ? entries[TEAMCLAW_AGENT_ID] : null;
+  const teamclawConfig = teamclawEntry && isRecord(teamclawEntry.config) ? teamclawEntry.config : null;
+  return teamclawConfig?.agentIsolationMode === TEAMCLAW_ISOLATION_MODE_MAIN
+    ? TEAMCLAW_ISOLATION_MODE_MAIN
+    : TEAMCLAW_ISOLATION_MODE_INDEPENDENT;
+}
+
+function resolveExplicitTeamClawWorkspaceDir(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const override = env.TEAMCLAW_WORKSPACE_DIR?.trim();
+  if (!override) {
+    return "";
+  }
+  return expandUserPath(override, homedir);
+}
+
+function loadOpenClawConfigRecord(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): Record<string, unknown> | null {
   const configPath = resolveDefaultOpenClawConfigPath(env, homedir);
   try {
     const raw = readFileSync(configPath, "utf8");
     const parsed = JSON5.parse(raw);
-    if (!isRecord(parsed)) {
-      return "";
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveConfiguredAgentEntry(
+  agentId: string,
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): Record<string, unknown> | null {
+  const parsed = loadOpenClawConfigRecord(env, homedir);
+  if (!parsed) {
+    return null;
+  }
+  const agents = isRecord(parsed.agents) ? parsed.agents : null;
+  const list = agents && Array.isArray(agents.list) ? agents.list : [];
+  const normalizedAgentId = normalizeAgentId(agentId);
+  for (const entry of list) {
+    if (!isRecord(entry)) {
+      continue;
     }
-    const agents = isRecord(parsed.agents) ? parsed.agents : null;
-    const defaults = agents && isRecord(agents.defaults) ? agents.defaults : null;
-    if (defaults && typeof defaults.workspace === "string" && defaults.workspace.trim()) {
-      return expandUserPath(defaults.workspace, homedir);
+    if (normalizeAgentId(entry.id) === normalizedAgentId) {
+      return entry;
     }
-  } catch {
-    // Fall back to the legacy state-dir-derived workspace path below.
+  }
+  return null;
+}
+
+function resolveConfiguredDefaultModelValue(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const parsed = loadOpenClawConfigRecord(env, homedir);
+  if (!parsed) {
+    return "";
+  }
+  const agents = isRecord(parsed.agents) ? parsed.agents : null;
+  const defaults = agents && isRecord(agents.defaults) ? agents.defaults : null;
+  const model = defaults?.model;
+  if (typeof model === "string") {
+    return model.trim();
+  }
+  if (isRecord(model) && typeof model.primary === "string") {
+    return model.primary.trim();
   }
   return "";
 }
 
+function resolveConfiguredTeamClawModelValue(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const teamclawEntry = resolveConfiguredAgentEntry(TEAMCLAW_AGENT_ID, env, homedir);
+  const model = teamclawEntry?.model;
+  if (typeof model === "string") {
+    return model.trim();
+  }
+  if (isRecord(model) && typeof model.primary === "string") {
+    return model.primary.trim();
+  }
+  return resolveConfiguredDefaultModelValue(env, homedir);
+}
+
+function cloneJsonValue<T>(value: T): T {
+  return value == null ? value : JSON.parse(JSON.stringify(value)) as T;
+}
+
+function resolveConfiguredDefaultAgentId(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const parsed = loadOpenClawConfigRecord(env, homedir);
+  if (!parsed) {
+    return "main";
+  }
+  const agents = isRecord(parsed.agents) ? parsed.agents : null;
+  const list = agents && Array.isArray(agents.list) ? agents.list.filter(isRecord) : [];
+  if (list.length === 0) {
+    return "main";
+  }
+  const defaultEntry = list.find((entry) => entry.default === true) ?? list[0];
+  return normalizeAgentId(defaultEntry.id);
+}
+
 export function resolveDefaultOpenClawHomeDir(
   env: NodeJS.ProcessEnv = process.env,
   homedir: () => string = os.homedir,
@@ -122,15 +260,207 @@ export function resolveDefaultOpenClawWorkspaceDir(
   return path.join(stateDir, "workspace");
 }
 
+export function resolveTeamClawAgentDir(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  if (resolveConfiguredTeamClawIsolationMode(env, homedir) === TEAMCLAW_ISOLATION_MODE_MAIN) {
+    return resolveDefaultAgentDir(env, homedir);
+  }
+  const configuredEntry = resolveConfiguredAgentEntry(TEAMCLAW_AGENT_ID, env, homedir);
+  if (configuredEntry && typeof configuredEntry.agentDir === "string" && configuredEntry.agentDir.trim()) {
+    return expandUserPath(configuredEntry.agentDir, homedir);
+  }
+  return path.join(resolveDefaultOpenClawStateDir(env, homedir), "agents", TEAMCLAW_AGENT_ID, "agent");
+}
+
+export type TeamClawModelReadiness = {
+  status: "ready" | "missing";
+  hasConfiguredModel: boolean;
+  hasAuthProfiles: boolean;
+  configuredModel: string;
+  authPath: string;
+  message: string;
+};
+
+export function getTeamClawModelReadiness(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): TeamClawModelReadiness {
+  const configuredModel = resolveConfiguredTeamClawModelValue(env, homedir);
+  const authCandidates = [
+    path.join(resolveTeamClawAgentDir(env, homedir), "auth-profiles.json"),
+    path.join(resolveDefaultAgentDir(env, homedir), "auth-profiles.json"),
+  ].filter((value, index, values) => values.indexOf(value) === index);
+  const authPath = authCandidates.find((candidatePath) => {
+    try {
+      return existsSync(candidatePath);
+    } catch {
+      return false;
+    }
+  }) ?? authCandidates[0] ?? "";
+  const hasConfiguredModel = Boolean(configuredModel);
+  const hasAuthProfiles = Boolean(authPath) && existsSync(authPath);
+  const status = hasConfiguredModel && hasAuthProfiles ? "ready" : "missing";
+  const missingParts = [];
+  if (!hasConfiguredModel) {
+    missingParts.push("no model is configured");
+  }
+  if (!hasAuthProfiles) {
+    missingParts.push("no auth-profiles.json was found");
+  }
+  return {
+    status,
+    hasConfiguredModel,
+    hasAuthProfiles,
+    configuredModel,
+    authPath,
+    message: status === "ready"
+      ? `TeamClaw is ready with model ${configuredModel}.`
+      : `TeamClaw cannot work yet because ${missingParts.join(" and ")}.`,
+  };
+}
+
+export function resolveDefaultAgentDir(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const defaultAgentId = resolveConfiguredDefaultAgentId(env, homedir);
+  const configuredEntry = resolveConfiguredAgentEntry(defaultAgentId, env, homedir);
+  if (configuredEntry && typeof configuredEntry.agentDir === "string" && configuredEntry.agentDir.trim()) {
+    return expandUserPath(configuredEntry.agentDir, homedir);
+  }
+  return path.join(resolveDefaultOpenClawStateDir(env, homedir), "agents", defaultAgentId, "agent");
+}
+
+export function resolveTeamClawAgentWorkspaceRootDir(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const explicitWorkspaceDir = resolveExplicitTeamClawWorkspaceDir(env, homedir);
+  if (explicitWorkspaceDir) {
+    return explicitWorkspaceDir;
+  }
+  if (resolveConfiguredTeamClawIsolationMode(env, homedir) === TEAMCLAW_ISOLATION_MODE_MAIN) {
+    return resolveDefaultOpenClawWorkspaceDir(env, homedir);
+  }
+  const configuredEntry = resolveConfiguredAgentEntry(TEAMCLAW_AGENT_ID, env, homedir);
+  if (configuredEntry && typeof configuredEntry.workspace === "string" && configuredEntry.workspace.trim()) {
+    return expandUserPath(configuredEntry.workspace, homedir);
+  }
+  return path.join(resolveDefaultOpenClawStateDir(env, homedir), `workspace-${TEAMCLAW_AGENT_ID}`);
+}
+
+export function buildTeamClawAgentSessionKey(
+  input: string,
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const trimmed = input.trim();
+  const agentMatch = trimmed.match(/^agent:[^:]+:(.+)$/i);
+  const logicalKey = (agentMatch?.[1] ?? trimmed).trim().toLowerCase() || "main";
+  if (resolveConfiguredTeamClawIsolationMode(env, homedir) === TEAMCLAW_ISOLATION_MODE_MAIN) {
+    return logicalKey;
+  }
+  return `agent:${TEAMCLAW_AGENT_ID}:${logicalKey}`;
+}
+
 export function resolveDefaultTeamClawRuntimeRootDir(
   env: NodeJS.ProcessEnv = process.env,
   homedir: () => string = os.homedir,
 ): string {
-  return path.join(path.dirname(resolveDefaultOpenClawWorkspaceDir(env, homedir)), "teamclaw-runtimes");
+  return path.join(resolveDefaultOpenClawStateDir(env, homedir), "teamclaw-runtimes");
+}
+
+/**
+ * TeamClaw-specific workspace directory.
+ *
+ * By default this resolves to a dedicated OpenClaw agent workspace sibling such as
+ * `<stateDir>/workspace-teamclaw`.
+ *
+ * When `agentIsolationMode` is set to `main`, TeamClaw falls back to the legacy
+ * shared layout and uses `<default-workspace>/teamclaw`.
+ */
+export function resolveTeamClawWorkspaceDir(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  if (resolveConfiguredTeamClawIsolationMode(env, homedir) === TEAMCLAW_ISOLATION_MODE_MAIN) {
+    return path.join(resolveTeamClawAgentWorkspaceRootDir(env, homedir), TEAMCLAW_AGENT_ID);
+  }
+  return resolveTeamClawAgentWorkspaceRootDir(env, homedir);
+}
+
+/**
+ * Resolve the `projects/` root inside the TeamClaw workspace.
+ * Each orchestration run or ad-hoc task gets its own subdirectory here.
+ */
+export function resolveTeamClawProjectsDir(
+  env?: NodeJS.ProcessEnv,
+  homedir?: () => string,
+): string {
+  return path.join(resolveTeamClawWorkspaceDir(env, homedir), "projects");
+}
+
+/**
+ * Resolve a project path relative to the active TeamClaw workspace.
+ * Workers operate inside the TeamClaw workspace itself, so project-local file
+ * operations should use `projects/<projectDir>` regardless of isolation mode.
+ */
+export function buildTeamClawProjectWorkspacePath(projectDir: string): string {
+  const normalized = String(projectDir || "").trim().replace(/^\/+|\/+$/gu, "");
+  return normalized ? `projects/${normalized}` : "projects";
+}
+
+/**
+ * Resolve a project path relative to the TeamClaw agent workspace root.
+ * Preview metadata is evaluated from the agent workspace root, which differs
+ * between `independent` and `main` isolation modes.
+ */
+export function buildTeamClawProjectAgentRelativePath(
+  projectDir: string,
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const workspaceRelative = buildTeamClawProjectWorkspacePath(projectDir);
+  const agentWorkspaceRoot = resolveTeamClawAgentWorkspaceRootDir(env, homedir);
+  const teamclawWorkspaceDir = resolveTeamClawWorkspaceDir(env, homedir);
+  const absoluteProjectPath = path.join(teamclawWorkspaceDir, workspaceRelative);
+  const relativeToAgentRoot = path.relative(agentWorkspaceRoot, absoluteProjectPath).replace(/\\/gu, "/");
+  return relativeToAgentRoot || ".";
+}
+
+/**
+ * Derive a filesystem-safe project slug from free-form text.
+ *
+ * 1. Lower-case, replace non-alphanumeric runs with hyphens, trim to ~50 chars.
+ * 2. Append a short random suffix to avoid collisions.
+ *
+ * Example: "Build a payment system with Stripe" → "build-a-payment-system-with-stripe-k3f9m2"
+ */
+export function deriveProjectSlug(text: string): string {
+  const slug = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 50)
+    .replace(/-+$/, "");
+  const suffix = randomSuffix(6);
+  return slug ? `${slug}-${suffix}` : suffix;
+}
+
+function randomSuffix(length: number): string {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return result;
 }
 
 export async function ensureOpenClawWorkspaceMemoryDir(logger: PluginLogger): Promise<string> {
-  const workspaceDir = resolveDefaultOpenClawWorkspaceDir();
+  await ensureTeamClawAgentBootstrap(logger);
+  const workspaceDir = resolveTeamClawWorkspaceDir();
   const memoryDir = path.join(workspaceDir, "memory");
   try {
     await fs.mkdir(workspaceDir, { recursive: true });
@@ -138,6 +468,7 @@ export async function ensureOpenClawWorkspaceMemoryDir(logger: PluginLogger): Pr
     await ensureFileIfMissing(path.join(workspaceDir, "AGENTS.md"), DEFAULT_AGENTS_MD);
     await ensureFileIfMissing(path.join(workspaceDir, "BOOTSTRAP.md"), DEFAULT_BOOTSTRAP_MD);
     await ensureFileIfMissing(path.join(workspaceDir, "HEARTBEAT.md"), DEFAULT_HEARTBEAT_MD);
+    await ensureFileIfMissing(path.join(memoryDir, "patterns.md"), DEFAULT_PATTERNS_MD);
   } catch (err) {
     logger.warn(
       `TeamClaw: failed to ensure OpenClaw workspace memory dir at ${memoryDir}: ${
@@ -148,6 +479,142 @@ export async function ensureOpenClawWorkspaceMemoryDir(logger: PluginLogger): Pr
   return memoryDir;
 }
 
+export async function ensureTeamClawAgentBootstrap(logger: PluginLogger): Promise<void> {
+  const teamclawAgentDir = resolveTeamClawAgentDir();
+  const teamclawWorkspaceRoot = resolveTeamClawAgentWorkspaceRootDir();
+  const isolationMode = resolveConfiguredTeamClawIsolationMode();
+  try {
+    await fs.mkdir(teamclawWorkspaceRoot, { recursive: true });
+    if (isolationMode === TEAMCLAW_ISOLATION_MODE_MAIN) {
+      return;
+    }
+    await ensureTeamClawAgentConfigBootstrap(logger);
+    await fs.mkdir(teamclawAgentDir, { recursive: true });
+    const sourceAgentDirs = [
+      resolveDefaultAgentDir(),
+      path.join(resolveDefaultOpenClawStateDir(), "agents", "main", "agent"),
+    ].filter((value, index, values) => values.indexOf(value) === index);
+    for (const sourceAgentDir of sourceAgentDirs) {
+      const sourceAuthProfilesPath = path.join(sourceAgentDir, "auth-profiles.json");
+      try {
+        await fs.access(sourceAuthProfilesPath);
+      } catch {
+        continue;
+      }
+      const targetAuthProfilesPath = path.join(teamclawAgentDir, "auth-profiles.json");
+      await fs.copyFile(sourceAuthProfilesPath, targetAuthProfilesPath);
+      logger.info(`TeamClaw: bootstrapped dedicated agent auth from ${sourceAuthProfilesPath}`);
+      break;
+    }
+  } catch (err) {
+    logger.warn(
+      `TeamClaw: failed to bootstrap dedicated agent runtime: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+async function ensureTeamClawAgentConfigBootstrap(logger: PluginLogger): Promise<void> {
+  const configPath = resolveDefaultOpenClawConfigPath();
+  let raw: string;
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch {
+    return;
+  }
+
+  let parsed: Record<string, unknown>;
+  try {
+    const candidate = JSON5.parse(raw);
+    if (!isRecord(candidate)) {
+      return;
+    }
+    parsed = candidate;
+  } catch {
+    return;
+  }
+
+  const agents = isRecord(parsed.agents) ? parsed.agents : {};
+  const defaults = isRecord(agents.defaults) ? agents.defaults : {};
+  const nextList = Array.isArray(agents.list) ? [...agents.list] : [];
+  const rootTools = isRecord(parsed.tools) ? parsed.tools : {};
+  const rootExec = isRecord(rootTools.exec) ? rootTools.exec : {};
+  const plugins = isRecord(parsed.plugins) ? parsed.plugins : {};
+  const entries = isRecord(plugins.entries) ? plugins.entries : {};
+  const teamclawPluginEntry = isRecord(entries[TEAMCLAW_AGENT_ID]) ? entries[TEAMCLAW_AGENT_ID] : {};
+  const existingPluginConfig = isRecord(teamclawPluginEntry.config) ? teamclawPluginEntry.config : {};
+  const teamclawWorkspaceDir = path.join(resolveDefaultOpenClawStateDir(), `workspace-${TEAMCLAW_AGENT_ID}`);
+  const teamclawAgentDir = path.join(resolveDefaultOpenClawStateDir(), "agents", TEAMCLAW_AGENT_ID, "agent");
+  const existingIndex = nextList.findIndex((entry) => isRecord(entry) && normalizeAgentId(entry.id) === TEAMCLAW_AGENT_ID);
+  const existingEntry = existingIndex >= 0 && isRecord(nextList[existingIndex]) ? nextList[existingIndex] : {};
+  const existingEntryTools = isRecord(existingEntry.tools) ? existingEntry.tools : {};
+  const existingEntryExec = isRecord(existingEntryTools.exec) ? existingEntryTools.exec : {};
+  const nextEntryExec: Record<string, unknown> = {
+    ...cloneJsonValue(rootExec),
+    ...cloneJsonValue(existingEntryExec),
+  };
+  if (typeof nextEntryExec.security !== "string" || !nextEntryExec.security.trim()) {
+    nextEntryExec.security = typeof rootExec.security === "string" && rootExec.security.trim()
+      ? rootExec.security.trim()
+      : TEAMCLAW_RECOMMENDED_EXEC_SECURITY;
+  }
+  if (typeof nextEntryExec.ask !== "string" || !nextEntryExec.ask.trim()) {
+    nextEntryExec.ask = typeof rootExec.ask === "string" && rootExec.ask.trim()
+      ? rootExec.ask.trim()
+      : TEAMCLAW_RECOMMENDED_EXEC_ASK;
+  }
+  const nextEntry: Record<string, unknown> = {
+    ...existingEntry,
+    id: TEAMCLAW_AGENT_ID,
+    workspace: typeof existingEntry.workspace === "string" && existingEntry.workspace.trim()
+      ? existingEntry.workspace
+      : teamclawWorkspaceDir,
+    agentDir: typeof existingEntry.agentDir === "string" && existingEntry.agentDir.trim()
+      ? existingEntry.agentDir
+      : teamclawAgentDir,
+    tools: {
+      ...cloneJsonValue(existingEntryTools),
+      exec: nextEntryExec,
+    },
+  };
+  if (nextEntry.model == null && defaults.model != null) {
+    nextEntry.model = cloneJsonValue(defaults.model);
+  }
+
+  const nextPluginConfig: Record<string, unknown> = {
+    ...existingPluginConfig,
+  };
+  if (
+    nextPluginConfig.mode === "controller"
+    && nextPluginConfig.processModel === "multi"
+    && nextPluginConfig.workerProvisioningType === "none"
+    && nextPluginConfig.workerProvisioningDisabled !== true
+  ) {
+    nextPluginConfig.workerProvisioningType = "process";
+  }
+
+  const entryChanged = JSON.stringify(existingEntry) !== JSON.stringify(nextEntry);
+  const pluginConfigChanged = JSON.stringify(existingPluginConfig) !== JSON.stringify(nextPluginConfig);
+  if (!entryChanged && !pluginConfigChanged) {
+    return;
+  }
+
+  if (existingIndex >= 0) {
+    nextList[existingIndex] = nextEntry;
+  } else {
+    nextList.push(nextEntry);
+  }
+  agents.list = nextList;
+  parsed.agents = agents;
+  if (pluginConfigChanged) {
+    teamclawPluginEntry.config = nextPluginConfig;
+    entries[TEAMCLAW_AGENT_ID] = teamclawPluginEntry;
+    plugins.entries = entries;
+    parsed.plugins = plugins;
+  }
+  await fs.writeFile(configPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+  logger.info(`TeamClaw: bootstrapped dedicated agent config into ${configPath}`);
+}
+
 async function ensureFileIfMissing(filePath: string, content: string): Promise<void> {
   try {
     await fs.access(filePath);