@frumu/tandem-panel 0.4.0 → 0.4.3

package/bin/setup.js

@@ -4,14 +4,15 @@ import { spawn } from "child_process";
 import { createServer } from "http";
 import { readFileSync, existsSync, createReadStream, createWriteStream } from "fs";
 import { mkdir, readdir, stat, rm, readFile, writeFile } from "fs/promises";
-import { randomBytes } from "crypto";
-import { join, dirname, extname, normalize, resolve, basename } from "path";
+import { createHash, randomBytes } from "crypto";
+import { join, dirname, extname, normalize, resolve, basename, relative } from "path";
 import { Transform } from "stream";
 import { pipeline } from "stream/promises";
 import { fileURLToPath } from "url";
 import { createRequire } from "module";
 import { homedir } from "os";
-import { ensureEnv } from "./init-env.js";
+import { ensureBootstrapEnv, resolveEnvLoadOrder } from "../lib/setup/env.js";
+import { createSwarmApiHandler } from "../server/routes/swarm.js";
 
 function parseDotEnv(content) {
   const out = {};
@@ -22,7 +23,10 @@ function parseDotEnv(content) {
     if (idx <= 0) continue;
     const key = line.slice(0, idx).trim();
     let value = line.slice(idx + 1).trim();
-    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
       value = value.slice(1, -1);
     }
     out[key] = value;
@@ -79,34 +83,56 @@ const cli = parseCliArgs(process.argv.slice(2));
 const rawArgs = process.argv.slice(2);
 const initRequested = cli.has("init");
 const resetTokenRequested = cli.has("reset-token");
+const explicitEnvFile = String(cli.value("env-file") || "").trim();
 const installServicesRequested = cli.has("install-services");
+const serviceOpRaw = String(cli.value("service-op") || "")
+  .trim()
+  .toLowerCase();
+const serviceOp = ["status", "start", "stop", "restart", "enable", "disable", "logs"].includes(
+  serviceOpRaw
+)
+  ? serviceOpRaw
+  : "";
 const serviceModeRaw = String(cli.value("service-mode") || "both")
   .trim()
   .toLowerCase();
 const serviceMode = ["both", "engine", "panel"].includes(serviceModeRaw) ? serviceModeRaw : "both";
 const serviceUserArg = String(cli.value("service-user") || "").trim();
-const serviceSetupOnly = rawArgs.length > 0 && rawArgs.every((arg) => {
-  if (arg === "--install-services") return true;
-  if (arg.startsWith("--service-mode")) return true;
-  if (arg.startsWith("--service-user")) return true;
-  return false;
-});
+const serviceSetupOnly =
+  rawArgs.length > 0 &&
+  rawArgs.every((arg) => {
+    if (arg === "--install-services") return true;
+    if (arg.startsWith("--service-op")) return true;
+    if (arg.startsWith("--service-mode")) return true;
+    if (arg.startsWith("--service-user")) return true;
+    return false;
+  });
 const cwdEnvPath = resolve(process.cwd(), ".env");
+for (const envPath of resolveEnvLoadOrder({ explicitEnvFile, cwd: process.cwd() })) {
+  loadDotEnvFile(envPath);
+}
 
 if (initRequested) {
-  const result = ensureEnv({ overwrite: resetTokenRequested });
+  const result = await ensureBootstrapEnv({
+    cwd: process.cwd(),
+    envPath: explicitEnvFile || undefined,
+    overwrite: resetTokenRequested,
+  });
   console.log("[Tandem Control Panel] Environment initialized.");
   console.log(`[Tandem Control Panel] .env:      ${result.envPath}`);
   console.log(`[Tandem Control Panel] Engine URL: ${result.engineUrl}`);
-  console.log(`[Tandem Control Panel] Panel URL:  http://localhost:${result.panelPort}`);
+  console.log(
+    `[Tandem Control Panel] Panel URL:  http://${result.panelHost}:${result.panelPort}`
+  );
   console.log(`[Tandem Control Panel] Token:      ${result.token}`);
-  if (process.argv.slice(2).length === 1 || (process.argv.slice(2).length === 2 && resetTokenRequested)) {
+  if (
+    process.argv.slice(2).length === 1 ||
+    (process.argv.slice(2).length === 2 && resetTokenRequested)
+  ) {
     process.exit(0);
   }
 }
 
-loadDotEnvFile(cwdEnvPath);
-
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DIST_DIR = join(__dirname, "..", "dist");
 const REPO_ROOT = resolve(__dirname, "..", "..", "..");
@@ -125,9 +151,20 @@ function resolveDefaultChannelUploadsRoot() {
 }
 
 const PORTAL_PORT = Number.parseInt(process.env.TANDEM_CONTROL_PANEL_PORT || "39732", 10);
+const PANEL_HOST = (process.env.TANDEM_CONTROL_PANEL_HOST || "127.0.0.1").trim() || "127.0.0.1";
+const PANEL_PUBLIC_URL = String(process.env.TANDEM_CONTROL_PANEL_PUBLIC_URL || "").trim();
 const ENGINE_HOST = (process.env.TANDEM_ENGINE_HOST || "127.0.0.1").trim();
 const ENGINE_PORT = Number.parseInt(process.env.TANDEM_ENGINE_PORT || "39731", 10);
-const ENGINE_URL = (process.env.TANDEM_ENGINE_URL || `http://${ENGINE_HOST}:${ENGINE_PORT}`).replace(/\/+$/, "");
+const ENGINE_URL = (
+  process.env.TANDEM_ENGINE_URL || `http://${ENGINE_HOST}:${ENGINE_PORT}`
+).replace(/\/+$/, "");
+const SWARM_RUNS_PATH = resolve(homedir(), ".tandem", "control-panel", "swarm-runs.json");
+const SWARM_HIDDEN_RUNS_PATH = resolve(
+  homedir(),
+  ".tandem",
+  "control-panel",
+  "swarm-hidden-runs.json"
+);
 const AUTO_START_ENGINE = (process.env.TANDEM_CONTROL_PANEL_AUTO_START_ENGINE || "1") !== "0";
 const CONFIGURED_ENGINE_TOKEN = (
   process.env.TANDEM_CONTROL_PANEL_ENGINE_TOKEN ||
@@ -136,7 +173,9 @@ const CONFIGURED_ENGINE_TOKEN = (
 ).trim();
 const SESSION_TTL_MS =
   Number.parseInt(process.env.TANDEM_CONTROL_PANEL_SESSION_TTL_MINUTES || "1440", 10) * 60 * 1000;
-const FILES_ROOT = resolve(process.env.TANDEM_CONTROL_PANEL_FILES_ROOT || resolveDefaultChannelUploadsRoot());
+const FILES_ROOT = resolve(
+  process.env.TANDEM_CONTROL_PANEL_FILES_ROOT || resolveDefaultChannelUploadsRoot()
+);
 const FILES_SCOPE = String(process.env.TANDEM_CONTROL_PANEL_FILES_SCOPE || "control-panel")
   .trim()
   .replace(/\\/g, "/")
@@ -144,11 +183,30 @@ const FILES_SCOPE = String(process.env.TANDEM_CONTROL_PANEL_FILES_SCOPE || "cont
   .replace(/\/+$/, "");
 const MAX_UPLOAD_BYTES = Math.max(
   1,
-  Number.parseInt(process.env.TANDEM_CONTROL_PANEL_MAX_UPLOAD_BYTES || `${250 * 1024 * 1024}`, 10) ||
-    250 * 1024 * 1024
+  Number.parseInt(
+    process.env.TANDEM_CONTROL_PANEL_MAX_UPLOAD_BYTES || `${250 * 1024 * 1024}`,
+    10
+  ) || 250 * 1024 * 1024
 );
 const require = createRequire(import.meta.url);
 const SETUP_ENTRYPOINT = fileURLToPath(import.meta.url);
+const CONTROL_PANEL_PACKAGE = (() => {
+  try {
+    return JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8"));
+  } catch {
+    return {};
+  }
+})();
+const CONTROL_PANEL_VERSION = String(CONTROL_PANEL_PACKAGE?.version || "0.0.0").trim() || "0.0.0";
+const CONTROL_PANEL_BUILD_FINGERPRINT = (() => {
+  try {
+    const source = readFileSync(SETUP_ENTRYPOINT);
+    const digest = createHash("sha1").update(source).digest("hex").slice(0, 8);
+    return `${CONTROL_PANEL_VERSION}-${digest}`;
+  } catch {
+    return `${CONTROL_PANEL_VERSION}-unknown`;
+  }
+})();
 
 const log = (msg) => console.log(`[Tandem Control Panel] ${msg}`);
 const err = (msg) => console.error(`[Tandem Control Panel] ERROR: ${msg}`);
@@ -190,10 +248,137 @@ const swarmState = {
   objective: "",
   workspaceRoot: REPO_ROOT,
   maxTasks: 3,
+  maxAgents: 3,
+  workflowId: "swarm.blackboard.default",
+  modelProvider: "",
+  modelId: "",
+  mcpServers: [],
+  repoRoot: "",
+  preflight: {
+    gitAvailable: null,
+    repoReady: true,
+    autoInitialized: false,
+    code: "workspace_ready",
+    reason: "",
+    guidance: "",
+  },
   lastError: "",
+  executorState: "idle",
+  executorReason: "",
+  executorMode: "context_steps",
+  resolvedModelProvider: "",
+  resolvedModelId: "",
+  modelResolutionSource: "none",
+  verificationMode: "strict",
+  runId: "",
+  attachedPid: null,
+  buildVersion: CONTROL_PANEL_VERSION,
+  buildFingerprint: CONTROL_PANEL_BUILD_FINGERPRINT,
+  buildStartedAt: Date.now(),
 };
+const swarmRunControllers = new Map();
 const swarmSseClients = new Set();
 
+function createSwarmRunController(runId = "", overrides = {}) {
+  return {
+    status: "idle",
+    startedAt: null,
+    stoppedAt: null,
+    objective: "",
+    workspaceRoot: REPO_ROOT,
+    maxTasks: 3,
+    maxAgents: 3,
+    workflowId: "swarm.blackboard.default",
+    modelProvider: "",
+    modelId: "",
+    mcpServers: [],
+    repoRoot: "",
+    lastError: "",
+    executorState: "idle",
+    executorReason: "",
+    executorMode: "context_steps",
+    resolvedModelProvider: "",
+    resolvedModelId: "",
+    modelResolutionSource: "none",
+    verificationMode: "strict",
+    runId: String(runId || "").trim(),
+    attachedPid: null,
+    registryCache: null,
+    reasons: [],
+    logs: [],
+    ...overrides,
+  };
+}
+
+function syncLegacySwarmState(controller) {
+  if (!controller || typeof controller !== "object") return;
+  swarmState.status = controller.status || swarmState.status;
+  swarmState.startedAt = controller.startedAt ?? swarmState.startedAt;
+  swarmState.stoppedAt = controller.stoppedAt ?? swarmState.stoppedAt;
+  swarmState.objective = controller.objective || swarmState.objective;
+  swarmState.workspaceRoot = controller.workspaceRoot || swarmState.workspaceRoot;
+  swarmState.maxTasks = controller.maxTasks ?? swarmState.maxTasks;
+  swarmState.maxAgents = controller.maxAgents ?? swarmState.maxAgents;
+  swarmState.workflowId = controller.workflowId || swarmState.workflowId;
+  swarmState.modelProvider = controller.modelProvider || swarmState.modelProvider;
+  swarmState.modelId = controller.modelId || swarmState.modelId;
+  swarmState.mcpServers = Array.isArray(controller.mcpServers)
+    ? controller.mcpServers
+    : swarmState.mcpServers;
+  swarmState.repoRoot = controller.repoRoot || swarmState.repoRoot;
+  swarmState.lastError = controller.lastError || "";
+  swarmState.executorState = controller.executorState || swarmState.executorState;
+  swarmState.executorReason = controller.executorReason || "";
+  swarmState.executorMode = controller.executorMode || swarmState.executorMode;
+  swarmState.resolvedModelProvider =
+    controller.resolvedModelProvider || swarmState.resolvedModelProvider;
+  swarmState.resolvedModelId = controller.resolvedModelId || swarmState.resolvedModelId;
+  swarmState.modelResolutionSource =
+    controller.modelResolutionSource || swarmState.modelResolutionSource;
+  swarmState.verificationMode = controller.verificationMode || swarmState.verificationMode;
+  swarmState.runId = controller.runId || swarmState.runId;
+  swarmState.attachedPid = controller.attachedPid || null;
+  swarmState.registryCache = controller.registryCache || null;
+}
+
+function getSwarmRunController(runId = "") {
+  const key = String(runId || "").trim();
+  if (!key) return null;
+  return swarmRunControllers.get(key) || null;
+}
+
+function upsertSwarmRunController(runId = "", patch = {}) {
+  const key = String(runId || "").trim();
+  if (!key) return null;
+  const current = getSwarmRunController(key) || createSwarmRunController(key);
+  const next = {
+    ...current,
+    ...patch,
+    runId: key,
+  };
+  swarmRunControllers.set(key, next);
+  if (String(swarmState.runId || "").trim() === key) {
+    syncLegacySwarmState(next);
+  }
+  return next;
+}
+
+function setActiveSwarmRunId(runId = "") {
+  const key = String(runId || "").trim();
+  swarmState.runId = key;
+  if (!key) {
+    swarmState.status = "idle";
+    swarmState.executorState = "idle";
+    swarmState.executorReason = "";
+    swarmState.lastError = "";
+    swarmState.attachedPid = null;
+    swarmState.registryCache = null;
+    return;
+  }
+  const controller = getSwarmRunController(key);
+  if (controller) syncLegacySwarmState(controller);
+}
+
 const sleep = (ms) => new Promise((resolveFn) => setTimeout(resolveFn, ms));
 
 function shellEscape(token) {
@@ -207,6 +392,7 @@ function runCmd(bin, args = [], options = {}) {
     const child = spawn(bin, args, {
       stdio: options.stdio || "pipe",
       env: options.env || process.env,
+      cwd: options.cwd || undefined,
     });
     let stdout = "";
     let stderr = "";
@@ -231,6 +417,279 @@ function runCmd(bin, args = [], options = {}) {
   });
 }
 
+async function loadSwarmRunsHistory() {
+  try {
+    const raw = await readFile(SWARM_RUNS_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed?.runs)) return [];
+    return parsed.runs
+      .filter((row) => row && typeof row === "object")
+      .map((row) => ({
+        runId: String(row.runId || "").trim(),
+        objective: String(row.objective || "").trim(),
+        workspaceRoot: String(row.workspaceRoot || "").trim(),
+        status: String(row.status || "unknown").trim(),
+        startedAt: Number(row.startedAt || 0) || 0,
+        stoppedAt: Number(row.stoppedAt || 0) || 0,
+        pid: Number(row.pid || 0) || null,
+        attached: row.attached === true,
+      }))
+      .filter((row) => row.runId || row.workspaceRoot || row.pid);
+  } catch {
+    return [];
+  }
+}
+
+async function saveSwarmRunsHistory(runs = []) {
+  const payload = JSON.stringify(
+    { version: 1, updatedAtMs: Date.now(), runs: runs.slice(-100) },
+    null,
+    2
+  );
+  await mkdir(dirname(SWARM_RUNS_PATH), { recursive: true });
+  await writeFile(SWARM_RUNS_PATH, payload, "utf8");
+}
+
+async function loadHiddenSwarmRunIds() {
+  try {
+    const raw = await readFile(SWARM_HIDDEN_RUNS_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    const ids = Array.isArray(parsed?.runIds) ? parsed.runIds : [];
+    return new Set(
+      ids
+        .map((id) => String(id || "").trim())
+        .filter(Boolean)
+        .slice(0, 5000)
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+async function saveHiddenSwarmRunIds(runIdSet) {
+  const runIds = Array.from(runIdSet)
+    .map((id) => String(id || "").trim())
+    .filter(Boolean)
+    .sort((a, b) => a.localeCompare(b));
+  await mkdir(dirname(SWARM_HIDDEN_RUNS_PATH), { recursive: true });
+  await writeFile(
+    SWARM_HIDDEN_RUNS_PATH,
+    JSON.stringify({ updatedAt: Date.now(), runIds }, null, 2),
+    "utf8"
+  );
+}
+
+async function recordSwarmRun(update = {}) {
+  try {
+    const runId = String(update.runId || "").trim() || randomBytes(8).toString("hex");
+    const runs = await loadSwarmRunsHistory();
+    const idx = runs.findIndex((row) => row.runId === runId);
+    const next = {
+      runId,
+      objective: String(update.objective || "").trim(),
+      workspaceRoot: String(update.workspaceRoot || "").trim(),
+      status: String(update.status || "unknown").trim(),
+      startedAt: Number(update.startedAt || 0) || Date.now(),
+      stoppedAt: Number(update.stoppedAt || 0) || 0,
+      pid: Number(update.pid || 0) || null,
+      attached: update.attached === true,
+    };
+    if (idx >= 0) runs[idx] = { ...runs[idx], ...next };
+    else runs.push(next);
+    await saveSwarmRunsHistory(runs);
+    return runId;
+  } catch {
+    return String(update.runId || "").trim();
+  }
+}
+
+function buildGitSafeEnv(baseEnv, safeDirectory) {
+  const env = { ...(baseEnv || process.env) };
+  const value = String(safeDirectory || "*").trim() || "*";
+  env.GIT_CONFIG_COUNT = "1";
+  env.GIT_CONFIG_KEY_0 = "safe.directory";
+  env.GIT_CONFIG_VALUE_0 = value;
+  return env;
+}
+
+function runGit(args = [], options = {}) {
+  return runCmd("git", args, {
+    ...options,
+    env: buildGitSafeEnv(options.env || process.env, options.safeDirectory),
+  });
+}
+
+function guidanceForGitInstall() {
+  if (process.platform === "darwin") {
+    return "Install Git: `xcode-select --install` or `brew install git`.";
+  }
+  if (process.platform === "win32") {
+    return "Install Git for Windows from https://git-scm.com/download/win and restart the app.";
+  }
+  return "Install Git using your package manager (for example `sudo apt install git`) and restart the app.";
+}
+
+function setSwarmPreflight(patch = {}) {
+  swarmState.preflight = {
+    gitAvailable: swarmState.preflight?.gitAvailable ?? null,
+    repoReady: swarmState.preflight?.repoReady ?? false,
+    autoInitialized: swarmState.preflight?.autoInitialized ?? false,
+    code: swarmState.preflight?.code || "",
+    reason: swarmState.preflight?.reason || "",
+    guidance: swarmState.preflight?.guidance || "",
+    ...patch,
+  };
+}
+
+async function detectGitAvailable() {
+  try {
+    await runGit(["--version"], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isGitRepo(cwd) {
+  try {
+    const out = await runGit(["-C", String(cwd || ""), "rev-parse", "--show-toplevel"], {
+      stdio: "pipe",
+      safeDirectory: "*",
+    });
+    const root = String(out.stdout || "").trim();
+    return root ? { ok: true, root, error: "" } : { ok: false, root: "", error: "" };
+  } catch (error) {
+    return { ok: false, root: "", error: String(error?.message || error || "") };
+  }
+}
+
+async function bootstrapEmptyGitRepo(workspaceRoot) {
+  await runGit(["init"], { cwd: workspaceRoot, stdio: "pipe", safeDirectory: workspaceRoot });
+  const readmePath = join(workspaceRoot, "README.md");
+  const ignorePath = join(workspaceRoot, ".gitignore");
+  if (!existsSync(readmePath)) {
+    await writeFile(
+      readmePath,
+      "# Swarm Workspace\n\nInitialized automatically for Tandem Swarm.\n",
+      "utf8"
+    );
+  }
+  if (!existsSync(ignorePath)) {
+    await writeFile(ignorePath, "node_modules/\n.DS_Store\n.swarm/worktrees/\n", "utf8");
+  }
+  await runGit(["add", "."], { cwd: workspaceRoot, stdio: "pipe", safeDirectory: workspaceRoot });
+  try {
+    await runGit(["commit", "-m", "Initialize swarm workspace"], {
+      cwd: workspaceRoot,
+      stdio: "pipe",
+      safeDirectory: workspaceRoot,
+    });
+  } catch (commitError) {
+    const message = String(commitError?.message || "");
+    if (!message.includes("Author identity unknown")) throw commitError;
+    await runGit(["config", "user.name", "Swarm Bootstrap"], {
+      cwd: workspaceRoot,
+      stdio: "pipe",
+      safeDirectory: workspaceRoot,
+    });
+    await runGit(["config", "user.email", "swarm@local"], {
+      cwd: workspaceRoot,
+      stdio: "pipe",
+      safeDirectory: workspaceRoot,
+    });
+    await runGit(["commit", "-m", "Initialize swarm workspace"], {
+      cwd: workspaceRoot,
+      stdio: "pipe",
+      safeDirectory: workspaceRoot,
+    });
+  }
+}
+
+async function preflightSwarmWorkspace(workspaceRoot, options = {}) {
+  const allowInitNonEmpty = options.allowInitNonEmpty === true;
+  const guidance = guidanceForGitInstall();
+  const gitAvailable = await detectGitAvailable();
+  if (!gitAvailable) {
+    return {
+      gitAvailable,
+      repoReady: false,
+      autoInitialized: false,
+      code: "git_missing",
+      repoRoot: "",
+      reason: "Git executable not found",
+      guidance,
+    };
+  }
+
+  const normalized = resolve(workspaceRoot);
+  if (!existsSync(normalized)) {
+    throw new Error(`Workspace root does not exist: ${normalized}`);
+  }
+  const details = await stat(normalized);
+  if (!details.isDirectory()) {
+    throw new Error(`Workspace root is not a directory: ${normalized}`);
+  }
+
+  const repo = await isGitRepo(normalized);
+  if (repo.ok) {
+    return {
+      gitAvailable: true,
+      repoReady: true,
+      autoInitialized: false,
+      code: "ok",
+      repoRoot: repo.root,
+      reason: "",
+      guidance,
+    };
+  }
+  const repoErrorText = String(repo.error || "");
+  const repoErrorLower = repoErrorText.toLowerCase();
+  if (
+    repoErrorText &&
+    !repoErrorLower.includes("not a git repository") &&
+    !repoErrorLower.includes("needed a single revision")
+  ) {
+    return {
+      gitAvailable: true,
+      repoReady: false,
+      autoInitialized: false,
+      code: "git_probe_failed",
+      repoRoot: "",
+      reason: `Git could not inspect the selected directory: ${repoErrorText}`,
+      guidance,
+    };
+  }
+
+  const entries = await readdir(normalized);
+  if (entries.length > 0 && !allowInitNonEmpty) {
+    const detail = repoErrorText ? ` Git probe output: ${repoErrorText}` : "";
+    return {
+      gitAvailable: true,
+      repoReady: false,
+      autoInitialized: false,
+      code: "not_repo_non_empty",
+      repoRoot: "",
+      reason: `Selected directory is not a Git repository and is not empty: ${normalized}. Choose an existing repo or an empty directory.${detail}`,
+      guidance,
+    };
+  }
+
+  await bootstrapEmptyGitRepo(normalized);
+  const initializedRepo = await isGitRepo(normalized);
+  if (!initializedRepo.ok) {
+    throw new Error(`Git repository initialization failed for ${normalized}`);
+  }
+  return {
+    gitAvailable: true,
+    repoReady: true,
+    autoInitialized: true,
+    code: allowInitNonEmpty ? "auto_initialized_non_empty" : "auto_initialized_empty",
+    repoRoot: initializedRepo.root,
+    reason: "",
+    guidance,
+  };
+}
+
 async function installServices() {
   if (process.platform !== "linux") {
     throw new Error("--install-services currently supports Linux/systemd only.");
@@ -239,7 +698,8 @@ async function installServices() {
     throw new Error("Service installation needs root privileges. Re-run with sudo.");
   }
 
-  const serviceUser = serviceUserArg || String(process.env.SUDO_USER || process.env.USER || "root").trim();
+  const serviceUser =
+    serviceUserArg || String(process.env.SUDO_USER || process.env.USER || "root").trim();
   if (!serviceUser) throw new Error("Could not determine service user.");
   const serviceGroup = serviceUser;
   const installEngine = serviceMode === "both" || serviceMode === "engine";
@@ -252,7 +712,9 @@ async function installServices() {
   const engineBin = String(process.env.TANDEM_ENGINE_BIN || "tandem-engine").trim();
   const token =
     CONFIGURED_ENGINE_TOKEN ||
-    (existsSync(engineEnvPath) ? parseDotEnv(readFileSync(engineEnvPath, "utf8")).TANDEM_API_TOKEN || "" : "") ||
+    (existsSync(engineEnvPath)
+      ? parseDotEnv(readFileSync(engineEnvPath, "utf8")).TANDEM_API_TOKEN || ""
+      : "") ||
     `tk_${randomBytes(16).toString("hex")}`;
 
   await mkdir("/etc/tandem", { recursive: true });
@@ -263,17 +725,17 @@ async function installServices() {
     log(`Warning: could not chown ${stateDir} to ${serviceUser}:${serviceGroup}: ${e.message}`);
   }
 
-  const existingEngineEnv = existsSync(engineEnvPath) ? parseDotEnv(readFileSync(engineEnvPath, "utf8")) : {};
+  const existingEngineEnv = existsSync(engineEnvPath)
+    ? parseDotEnv(readFileSync(engineEnvPath, "utf8"))
+    : {};
   const engineEnv = {
     ...existingEngineEnv,
     TANDEM_API_TOKEN: token,
     TANDEM_STATE_DIR: stateDir,
     TANDEM_MEMORY_DB_PATH: existingEngineEnv.TANDEM_MEMORY_DB_PATH || `${stateDir}/memory.sqlite`,
     TANDEM_ENABLE_GLOBAL_MEMORY: existingEngineEnv.TANDEM_ENABLE_GLOBAL_MEMORY || "1",
-    TANDEM_DISABLE_TOOL_GUARD_BUDGETS:
-      existingEngineEnv.TANDEM_DISABLE_TOOL_GUARD_BUDGETS || "1",
-    TANDEM_TOOL_ROUTER_ENABLED:
-      existingEngineEnv.TANDEM_TOOL_ROUTER_ENABLED || "0",
+    TANDEM_DISABLE_TOOL_GUARD_BUDGETS: existingEngineEnv.TANDEM_DISABLE_TOOL_GUARD_BUDGETS || "1",
+    TANDEM_TOOL_ROUTER_ENABLED: existingEngineEnv.TANDEM_TOOL_ROUTER_ENABLED || "0",
     TANDEM_PROMPT_CONTEXT_HOOK_TIMEOUT_MS:
       existingEngineEnv.TANDEM_PROMPT_CONTEXT_HOOK_TIMEOUT_MS || "5000",
     TANDEM_PROVIDER_STREAM_CONNECT_TIMEOUT_MS:
@@ -282,8 +744,7 @@ async function installServices() {
       existingEngineEnv.TANDEM_PROVIDER_STREAM_IDLE_TIMEOUT_MS || "90000",
     TANDEM_PERMISSION_WAIT_TIMEOUT_MS:
       existingEngineEnv.TANDEM_PERMISSION_WAIT_TIMEOUT_MS || "15000",
-    TANDEM_TOOL_EXEC_TIMEOUT_MS:
-      existingEngineEnv.TANDEM_TOOL_EXEC_TIMEOUT_MS || "45000",
+    TANDEM_TOOL_EXEC_TIMEOUT_MS: existingEngineEnv.TANDEM_TOOL_EXEC_TIMEOUT_MS || "45000",
     TANDEM_BASH_TIMEOUT_MS: existingEngineEnv.TANDEM_BASH_TIMEOUT_MS || "30000",
   };
   const engineEnvBody = Object.entries(engineEnv)
@@ -293,7 +754,9 @@ async function installServices() {
   await runCmd("chmod", ["640", engineEnvPath]);
 
   const panelAutoStart = serviceMode === "panel" ? "1" : "0";
-  const existingPanelEnv = existsSync(panelEnvPath) ? parseDotEnv(readFileSync(panelEnvPath, "utf8")) : {};
+  const existingPanelEnv = existsSync(panelEnvPath)
+    ? parseDotEnv(readFileSync(panelEnvPath, "utf8"))
+    : {};
   const panelEnv = {
     ...existingPanelEnv,
     TANDEM_CONTROL_PANEL_PORT: String(PORTAL_PORT),
@@ -365,10 +828,14 @@ WantedBy=multi-user.target
 
   await runCmd("systemctl", ["daemon-reload"], { stdio: "inherit" });
   if (installEngine) {
-    await runCmd("systemctl", ["enable", "--now", `${engineServiceName}.service`], { stdio: "inherit" });
+    await runCmd("systemctl", ["enable", "--now", `${engineServiceName}.service`], {
+      stdio: "inherit",
+    });
   }
   if (installPanel) {
-    await runCmd("systemctl", ["enable", "--now", `${panelServiceName}.service`], { stdio: "inherit" });
+    await runCmd("systemctl", ["enable", "--now", `${panelServiceName}.service`], {
+      stdio: "inherit",
+    });
   }
 
   log("Services installed.");
@@ -381,6 +848,45 @@ WantedBy=multi-user.target
   log(`Token: ${token}`);
 }
 
+function selectedServiceUnits(mode) {
+  const normalized = String(mode || "both")
+    .trim()
+    .toLowerCase();
+  if (normalized === "engine") return ["tandem-engine.service"];
+  if (normalized === "panel") return ["tandem-control-panel.service"];
+  return ["tandem-engine.service", "tandem-control-panel.service"];
+}
+
+async function operateServices(operation, mode) {
+  const op = String(operation || "")
+    .trim()
+    .toLowerCase();
+  if (!op) return;
+  if (process.platform !== "linux") {
+    throw new Error("--service-op currently supports Linux/systemd only.");
+  }
+  const units = selectedServiceUnits(mode);
+  if (op === "logs") {
+    const args = units
+      .flatMap((unit) => ["-u", unit])
+      .concat(["-n", "120", "-f", "-o", "short-iso"]);
+    await runCmd("journalctl", args, { stdio: "inherit" });
+    return;
+  }
+  if (op === "status") {
+    await runCmd("systemctl", ["--no-pager", "--full", "status", ...units], { stdio: "inherit" });
+    return;
+  }
+  if (!["start", "stop", "restart", "enable", "disable"].includes(op)) {
+    throw new Error(
+      "Invalid --service-op. Expected one of: status,start,stop,restart,enable,disable,logs"
+    );
+  }
+  for (const unit of units) {
+    await runCmd("systemctl", [op, unit], { stdio: "inherit" });
+  }
+}
+
 function isLocalEngineUrl(url) {
   try {
     const u = new URL(url);
@@ -472,7 +978,9 @@ function pushSwarmEvent(kind, payload = {}) {
 }
 
 function appendSwarmLog(stream, text) {
-  const lines = String(text || "").split(/\r?\n/).filter(Boolean);
+  const lines = String(text || "")
+    .split(/\r?\n/)
+    .filter(Boolean);
   for (const line of lines) {
     swarmState.logs.push({ at: Date.now(), stream, line });
     if (swarmState.logs.length > 800) swarmState.logs.shift();
@@ -480,78 +988,6 @@ function appendSwarmLog(stream, text) {
   }
 }
 
-function appendSwarmReason(reason) {
-  const item = { at: Date.now(), ...reason };
-  swarmState.reasons.push(item);
-  if (swarmState.reasons.length > 500) swarmState.reasons.shift();
-  pushSwarmEvent("reason", item);
-}
-
-function compareRegistryTransitions(previousRegistry, nextRegistry) {
-  const prevTasks = previousRegistry?.tasks || {};
-  const nextTasks = nextRegistry?.tasks || {};
-  const transitions = [];
-
-  for (const [taskId, next] of Object.entries(nextTasks)) {
-    const prev = prevTasks[taskId];
-    if (!prev) {
-      transitions.push({
-        kind: "task_transition",
-        taskId,
-        from: "new",
-        to: next.status || "unknown",
-        role: next.ownerRole || "",
-        reason: next.statusReason || "task registered",
-      });
-      continue;
-    }
-    if ((prev.status || "") !== (next.status || "")) {
-      transitions.push({
-        kind: "task_transition",
-        taskId,
-        from: prev.status || "unknown",
-        to: next.status || "unknown",
-        role: next.ownerRole || "",
-        reason: next.statusReason || `${prev.status || "unknown"} -> ${next.status || "unknown"}`,
-      });
-    } else if ((prev.statusReason || "") !== (next.statusReason || "") && next.statusReason) {
-      transitions.push({
-        kind: "task_reason",
-        taskId,
-        from: next.status || "unknown",
-        to: next.status || "unknown",
-        role: next.ownerRole || "",
-        reason: next.statusReason,
-      });
-    }
-  }
-
-  return transitions;
-}
-
-async function monitorSwarmRegistry(token) {
-  try {
-    const latest = await readSwarmRegistry(token);
-    const latestValue = latest?.value || { tasks: {} };
-    const previous = swarmState.registryCache?.value || { tasks: {} };
-    const transitions = compareRegistryTransitions(previous, latestValue);
-    if (transitions.length > 0) {
-      for (const t of transitions) appendSwarmReason(t);
-      pushSwarmEvent("registry_update", { count: transitions.length });
-    }
-    swarmState.registryCache = latest;
-  } catch (e) {
-    appendSwarmLog("stderr", `[swarm-monitor] ${e instanceof Error ? e.message : String(e)}`);
-  }
-}
-
-function clearSwarmMonitor() {
-  if (swarmState.monitorTimer) {
-    clearInterval(swarmState.monitorTimer);
-    swarmState.monitorTimer = null;
-  }
-}
-
 async function engineHealth(token = "") {
   try {
     const response = await fetch(`${ENGINE_URL}/global/health`, {
@@ -595,7 +1031,9 @@ async function ensureEngineRunning() {
       log(
         "Note: TANDEM_CONTROL_PANEL_ENGINE_TOKEN is only applied when control panel starts a new engine process."
       );
-      log("Use the existing engine's token, or stop that engine to let control panel start one with your configured token.");
+      log(
+        "Use the existing engine's token, or stop that engine to let control panel start one with your configured token."
+      );
     }
     return;
   }
@@ -615,25 +1053,28 @@ async function ensureEngineRunning() {
   log(`Starting Tandem Engine at ${ENGINE_URL}...`);
   engineProcess = spawn(
     process.execPath,
-    [engineEntrypoint, "serve", "--hostname", url.hostname, "--port", String(url.port || ENGINE_PORT)],
+    [
+      engineEntrypoint,
+      "serve",
+      "--hostname",
+      url.hostname,
+      "--port",
+      String(url.port || ENGINE_PORT),
+    ],
     {
       env: {
         ...process.env,
         TANDEM_API_TOKEN: managedEngineToken,
-        TANDEM_DISABLE_TOOL_GUARD_BUDGETS:
-          process.env.TANDEM_DISABLE_TOOL_GUARD_BUDGETS || "1",
-        TANDEM_TOOL_ROUTER_ENABLED:
-          process.env.TANDEM_TOOL_ROUTER_ENABLED || "0",
+        TANDEM_DISABLE_TOOL_GUARD_BUDGETS: process.env.TANDEM_DISABLE_TOOL_GUARD_BUDGETS || "1",
+        TANDEM_TOOL_ROUTER_ENABLED: process.env.TANDEM_TOOL_ROUTER_ENABLED || "0",
         TANDEM_PROMPT_CONTEXT_HOOK_TIMEOUT_MS:
           process.env.TANDEM_PROMPT_CONTEXT_HOOK_TIMEOUT_MS || "5000",
         TANDEM_PROVIDER_STREAM_CONNECT_TIMEOUT_MS:
           process.env.TANDEM_PROVIDER_STREAM_CONNECT_TIMEOUT_MS || "30000",
         TANDEM_PROVIDER_STREAM_IDLE_TIMEOUT_MS:
           process.env.TANDEM_PROVIDER_STREAM_IDLE_TIMEOUT_MS || "90000",
-        TANDEM_PERMISSION_WAIT_TIMEOUT_MS:
-          process.env.TANDEM_PERMISSION_WAIT_TIMEOUT_MS || "15000",
-        TANDEM_TOOL_EXEC_TIMEOUT_MS:
-          process.env.TANDEM_TOOL_EXEC_TIMEOUT_MS || "45000",
+        TANDEM_PERMISSION_WAIT_TIMEOUT_MS: process.env.TANDEM_PERMISSION_WAIT_TIMEOUT_MS || "15000",
+        TANDEM_TOOL_EXEC_TIMEOUT_MS: process.env.TANDEM_TOOL_EXEC_TIMEOUT_MS || "45000",
         TANDEM_BASH_TIMEOUT_MS: process.env.TANDEM_BASH_TIMEOUT_MS || "30000",
       },
       stdio: "inherit",
@@ -641,7 +1082,9 @@ async function ensureEngineRunning() {
   );
   log(`Engine API token for this process: ${managedEngineToken}`);
   if (!CONFIGURED_ENGINE_TOKEN) {
-    log("Token was auto-generated. Set TANDEM_CONTROL_PANEL_ENGINE_TOKEN (or TANDEM_API_TOKEN) to keep it stable.");
+    log(
+      "Token was auto-generated. Set TANDEM_CONTROL_PANEL_ENGINE_TOKEN (or TANDEM_API_TOKEN) to keep it stable."
+    );
   }
 
   engineProcess.on("error", (e) => err(`Failed to start engine: ${e.message}`));
@@ -676,7 +1119,8 @@ function toSafeRelPath(raw) {
   if (normalized.includes("\0")) return null;
   const full = resolve(FILES_ROOT, normalized);
   if (full !== FILES_ROOT && !full.startsWith(`${FILES_ROOT}/`)) return null;
-  if (FILES_SCOPE && normalized !== FILES_SCOPE && !normalized.startsWith(`${FILES_SCOPE}/`)) return null;
+  if (FILES_SCOPE && normalized !== FILES_SCOPE && !normalized.startsWith(`${FILES_SCOPE}/`))
+    return null;
   return normalized;
 }
 
@@ -931,7 +1375,11 @@ async function handleAuthLogin(req, res) {
     sendJson(res, 200, {
       ok: true,
       requiresToken: !!health.apiTokenRequired,
-      engine: { url: ENGINE_URL, version: health.version || "unknown", local: isLocalEngineUrl(ENGINE_URL) },
+      engine: {
+        url: ENGINE_URL,
+        version: health.version || "unknown",
+        local: isLocalEngineUrl(ENGINE_URL),
+      },
     });
   } catch (e) {
     sendJson(res, 400, { ok: false, error: e instanceof Error ? e.message : String(e) });
@@ -976,7 +1424,10 @@ async function proxyEngineRequest(req, res, session) {
       duplex: hasBody ? "half" : undefined,
     });
   } catch (e) {
-    sendJson(res, 502, { ok: false, error: `Engine unreachable: ${e instanceof Error ? e.message : String(e)}` });
+    sendJson(res, 502, {
+      ok: false,
+      error: `Engine unreachable: ${e instanceof Error ? e.message : String(e)}`,
+    });
     return;
   }
 
@@ -1023,183 +1474,2870 @@ async function proxyEngineRequest(req, res, session) {
   }
 }
 
-async function readSwarmRegistry(token) {
-  const keys = ["swarm.active_tasks", "project/swarm.active_tasks"];
-  for (const key of keys) {
+function contextStepStatusToLegacyTaskStatus(status) {
+  switch (
+    String(status || "")
+      .trim()
+      .toLowerCase()
+  ) {
+    case "in_progress":
+      return "running";
+    case "runnable":
+    case "pending":
+      return "pending";
+    case "blocked":
+      return "blocked";
+    case "done":
+      return "complete";
+    case "failed":
+      return "failed";
+    default:
+      return "pending";
+  }
+}
+
+function contextRunStatusToSwarmStatus(status) {
+  const normalized = String(status || "")
+    .trim()
+    .toLowerCase();
+  if (
+    [
+      "queued",
+      "planning",
+      "awaiting_approval",
+      "running",
+      "paused",
+      "blocked",
+      "completed",
+      "failed",
+      "cancelled",
+    ].includes(normalized)
+  ) {
+    return normalized;
+  }
+  return "idle";
+}
+
+function buildWorkspaceId(workspaceRoot) {
+  const digest = createHash("sha1")
+    .update(String(workspaceRoot || ""))
+    .digest("hex");
+  return `ws-${digest.slice(0, 16)}`;
+}
+
+function workspaceExistsAsDirectory(workspaceRoot) {
+  const normalized = resolve(String(workspaceRoot || "").trim());
+  if (!existsSync(normalized)) return null;
+  return stat(normalized)
+    .then((info) => (info.isDirectory() ? normalized : null))
+    .catch(() => null);
+}
+
+async function engineRequestJson(session, path, options = {}) {
+  const method = String(options.method || "GET").toUpperCase();
+  const body = options.body;
+  const maxNetworkRetries = options.maxNetworkRetries ?? 2;
+  const isEngineStarting = (value) =>
+    typeof value === "string" &&
+    (value.includes("ENGINE_STARTING") ||
+      value.includes("Engine starting") ||
+      value.includes("Service Unavailable"));
+  let response = null;
+  let lastError = null;
+  for (let attempt = 0; attempt <= maxNetworkRetries; attempt += 1) {
+    if (attempt > 0) await sleep(1000 * attempt);
     try {
-      const response = await fetch(`${ENGINE_URL}/resource/${encodeURIComponent(key)}`, {
+      response = await fetch(`${ENGINE_URL}${path}`, {
+        method,
         headers: {
-          authorization: `Bearer ${token}`,
-          "x-tandem-token": token,
+          authorization: `Bearer ${session.token}`,
+          "x-tandem-token": session.token,
+          ...(body ? { "content-type": "application/json" } : {}),
+          ...(options.headers || {}),
         },
-        signal: AbortSignal.timeout(1200),
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(options.timeoutMs || 8000),
       });
-      if (!response.ok) continue;
-      const record = await response.json();
-      if (record?.value && typeof record.value === "object") {
-        return { key, value: record.value };
+    } catch (error) {
+      const name = String(error?.name || "");
+      const isTimeout = name === "AbortError" || name === "TimeoutError";
+      if (isTimeout || attempt >= maxNetworkRetries) throw error;
+      lastError = error;
+      continue;
+    }
+    if (!response.ok) {
+      const rawText = await response.text().catch(() => "");
+      if (
+        (response.status === 503 || isEngineStarting(rawText)) &&
+        attempt < maxNetworkRetries
+      ) {
+        lastError = new Error(rawText || `${method} ${path} failed: ${response.status}`);
+        response = null;
+        continue;
       }
-    } catch {
-      // ignore
+      let detail = `${method} ${path} failed: ${response.status}`;
+      if (rawText.trim()) {
+        try {
+          const payload = JSON.parse(rawText);
+          detail = String(payload?.error || payload?.message || detail);
+        } catch {
+          detail = rawText || detail;
+        }
+      }
+      throw new Error(detail);
     }
+    break;
   }
-  return { key: "swarm.active_tasks", value: { version: 1, updatedAtMs: Date.now(), tasks: {} } };
+  if (!response) throw lastError || new Error(`${method} ${path} failed`);
+  if (response.status === 204) return {};
+  const text = await response.text();
+  if (!text.trim()) return {};
+  return JSON.parse(text);
 }
 
-function stopSwarm() {
-  if (!swarmState.process) return;
-  swarmState.status = "stopping";
-  clearSwarmMonitor();
-  swarmState.process.kill("SIGTERM");
-  pushSwarmEvent("status", { status: swarmState.status });
+function contextRunToTasks(run) {
+  const steps = Array.isArray(run?.steps) ? run.steps : [];
+  return steps.map((step) => ({
+    taskId: String(step.step_id || ""),
+    title: String(step.title || step.step_id || "Untitled step"),
+    ownerRole: "context_driver",
+    status: contextStepStatusToLegacyTaskStatus(step.status),
+    stepStatus: String(step.status || "pending"),
+    statusReason: String(run?.why_next_step || ""),
+    lastUpdateMs: Number(run?.updated_at_ms || Date.now()),
+    runId: String(run?.run_id || ""),
+    sessionId: `context-${String(run?.run_id || "")}`,
+    branch: "",
+    worktreePath: "",
+  }));
 }
 
-function startSwarm(session, config = {}) {
-  if (!isLocalEngineUrl(ENGINE_URL)) {
-    throw new Error("Swarm orchestration is disabled when using a remote engine URL.");
-  }
-  if (swarmState.process) {
-    throw new Error("Swarm runtime is already running.");
-  }
+function eventsToReasons(events = []) {
+  return events
+    .map((evt) => {
+      const payload = evt?.payload && typeof evt.payload === "object" ? evt.payload : {};
+      return {
+        at: Number(evt?.ts_ms || Date.now()),
+        kind: "task_transition",
+        taskId: String(evt?.step_id || payload?.step_id || "run"),
+        role: "context_driver",
+        from: "",
+        to: String(evt?.status || ""),
+        reason: String(payload?.why_next_step || payload?.error || evt?.type || "updated"),
+      };
+    })
+    .slice(-250);
+}
 
-  const objective = String(config.objective || "Ship a small feature end-to-end").trim();
-  const workspaceRoot = String(config.workspaceRoot || REPO_ROOT).trim();
-  const maxTasks = Math.max(1, Number.parseInt(String(config.maxTasks || 3), 10) || 3);
+function eventsToLogs(events = []) {
+  return events
+    .map((evt) => {
+      const payload = evt?.payload && typeof evt.payload === "object" ? evt.payload : {};
+      const details = payload?.error || payload?.why_next_step || "";
+      const line = details
+        ? `${evt?.type || "event"} ${evt?.status || ""}: ${details}`
+        : `${evt?.type || "event"} ${evt?.status || ""}`.trim();
+      return {
+        at: Number(evt?.ts_ms || Date.now()),
+        stream: "event",
+        line,
+      };
+    })
+    .slice(-300);
+}
+
+async function contextRunSnapshot(session, runId) {
+  const [runPayload, eventsPayload, blackboardPayload, replayPayload, patchesPayload] =
+    await Promise.all([
+      engineRequestJson(session, `/context/runs/${encodeURIComponent(runId)}`),
+      engineRequestJson(session, `/context/runs/${encodeURIComponent(runId)}/events?tail=300`),
+      engineRequestJson(session, `/context/runs/${encodeURIComponent(runId)}/blackboard`).catch(
+        () => ({})
+      ),
+      engineRequestJson(session, `/context/runs/${encodeURIComponent(runId)}/replay`).catch(
+        () => ({})
+      ),
+      engineRequestJson(
+        session,
+        `/context/runs/${encodeURIComponent(runId)}/blackboard/patches?tail=300`
+      ).catch(() => ({})),
+    ]);
+  const run = runPayload?.run || {};
+  const events = Array.isArray(eventsPayload?.events) ? eventsPayload.events : [];
+  const blackboardPatches = Array.isArray(patchesPayload?.patches) ? patchesPayload.patches : [];
+  const tasks = contextRunToTasks(run);
+  const taskMap = Object.fromEntries(tasks.map((task) => [task.taskId, task]));
+  return {
+    run,
+    events,
+    blackboard: blackboardPayload?.blackboard || null,
+    blackboardPatches,
+    replay: replayPayload || null,
+    registry: {
+      key: "context.run.steps",
+      value: {
+        version: 1,
+        updatedAtMs: Number(run?.updated_at_ms || Date.now()),
+        tasks: taskMap,
+      },
+    },
+    reasons: eventsToReasons(events),
+    logs: eventsToLogs(events),
+  };
+}
 
-  const managerPath = join(REPO_ROOT, "examples", "agent-swarm", "src", "manager.mjs");
-  if (!existsSync(managerPath)) {
-    throw new Error(`Missing swarm manager at ${managerPath}`);
-  }
-
-  swarmState.logs = [];
-  swarmState.reasons = [];
-  swarmState.status = "starting";
-  swarmState.startedAt = Date.now();
-  swarmState.stoppedAt = null;
-  swarmState.objective = objective;
-  swarmState.workspaceRoot = workspaceRoot;
-  swarmState.maxTasks = maxTasks;
-  swarmState.lastError = "";
-  swarmState.registryCache = null;
-
-  pushSwarmEvent("status", { status: swarmState.status, objective, workspaceRoot, maxTasks });
-
-  const child = spawn(process.execPath, [managerPath, objective], {
-    cwd: workspaceRoot,
-    env: {
-      ...process.env,
-      TANDEM_BASE_URL: ENGINE_URL,
-      TANDEM_API_TOKEN: session.token,
-      SWARM_MAX_TASKS: String(maxTasks),
-      SWARM_OBJECTIVE: objective,
+async function appendContextRunEvent(
+  session,
+  runId,
+  eventType,
+  status,
+  payload = {},
+  stepId = null
+) {
+  return engineRequestJson(session, `/context/runs/${encodeURIComponent(runId)}/events`, {
+    method: "POST",
+    body: {
+      type: eventType,
+      status,
+      step_id: stepId || undefined,
+      payload,
     },
-    stdio: ["ignore", "pipe", "pipe"],
   });
+}
 
-  swarmState.process = child;
+function parseObjectiveTodos(objective, max = 6) {
+  const compact = String(objective || "")
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^[-*#\d\.\)\[\]\s]+/, "").trim())
+    .filter(Boolean)
+    .join(" ");
+  const normalized = compact.replace(/\s+/g, " ").trim();
+  if (!normalized) return ["Execute requested objective"];
+  const maxChars = Math.max(80, Number(max || 6) * 80);
+  const content =
+    normalized.length > maxChars ? `${normalized.slice(0, maxChars).trimEnd()}...` : normalized;
+  return [content];
+}
 
-  child.stdout.on("data", (chunk) => appendSwarmLog("stdout", chunk));
-  child.stderr.on("data", (chunk) => appendSwarmLog("stderr", chunk));
+function textFromMessageParts(parts) {
+  if (!Array.isArray(parts)) return "";
+  return parts
+    .map((part) => {
+      if (!part) return "";
+      if (typeof part === "string") return part;
+      if (typeof part.text === "string") return part.text;
+      if (typeof part.delta === "string") return part.delta;
+      if (typeof part.content === "string") return part.content;
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+}
 
-  child.on("spawn", () => {
-    swarmState.status = "running";
-    pushSwarmEvent("status", { status: swarmState.status });
-    void monitorSwarmRegistry(session.token);
-    swarmState.monitorTimer = setInterval(() => {
-      if (swarmState.status === "running") void monitorSwarmRegistry(session.token);
-    }, 2000);
-  });
+function roleOfMessage(row) {
+  return String(
+    row?.info?.role || row?.role || row?.message_role || row?.type || row?.author || "assistant"
+  )
+    .trim()
+    .toLowerCase();
+}
 
-  child.on("error", (e) => {
-    swarmState.status = "error";
-    swarmState.lastError = e.message;
-    clearSwarmMonitor();
-    appendSwarmLog("stderr", e.message);
-    pushSwarmEvent("status", { status: swarmState.status, error: e.message });
-  });
+function textOfMessage(row) {
+  const fromParts = textFromMessageParts(row?.parts);
+  if (fromParts) return fromParts;
+  const direct = [row?.content, row?.text, row?.message, row?.delta, row?.body].find(
+    (value) => typeof value === "string" && value.trim().length > 0
+  );
+  if (typeof direct === "string") return direct.trim();
+  if (Array.isArray(row?.content)) {
+    return row.content
+      .map((chunk) => {
+        if (!chunk) return "";
+        if (typeof chunk === "string") return chunk;
+        if (typeof chunk?.text === "string") return chunk.text;
+        if (typeof chunk?.content === "string") return chunk.content;
+        return "";
+      })
+      .filter(Boolean)
+      .join("\n")
+      .trim();
+  }
+  return "";
+}
+
+function extractAssistantText(rows) {
+  const list = Array.isArray(rows) ? rows : [];
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    if (roleOfMessage(list[i]) !== "assistant") continue;
+    const text = textOfMessage(list[i]);
+    if (text) return text;
+  }
+  return "";
+}
 
-  child.on("exit", (code, signal) => {
-    const failed = code && code !== 0;
-    swarmState.status = failed ? "error" : "idle";
-    swarmState.stoppedAt = Date.now();
-    swarmState.lastError = failed ? `Exited with code ${code}` : "";
-    swarmState.process = null;
-    clearSwarmMonitor();
-    pushSwarmEvent("status", {
-      status: swarmState.status,
-      code,
-      signal,
-      error: swarmState.lastError || undefined,
+function normalizePlannerTasks(rawTasks, maxTasks = 8, options = {}) {
+  const normalizedMax = Math.max(1, Number(maxTasks) || 8);
+  const linearFallback = options?.linearFallback === true;
+  const candidates = Array.isArray(rawTasks) ? rawTasks : [];
+  const normalizeTaskKind = (value, outputTarget) => {
+    const raw = String(value || "").trim().toLowerCase();
+    if (["implementation", "inspection", "research", "validation"].includes(raw)) return raw;
+    return outputTarget?.path ? "implementation" : "inspection";
+  };
+  const normalizeOutputTarget = (value) => {
+    if (!value || typeof value !== "object") return null;
+    const path = String(value?.path || value?.file || value?.file_path || value?.target || "").trim();
+    if (!path) return null;
+    const kind = String(value?.kind || value?.type || "artifact").trim().toLowerCase() || "artifact";
+    const operation = String(value?.operation || value?.mode || "").trim().toLowerCase() || "create_or_update";
+    return { path, kind, operation };
+  };
+  const provisional = candidates
+    .map((row, index) => {
+      if (typeof row === "string") {
+        const title = String(row || "").trim();
+        if (title.length < 6) return null;
+        return {
+          id: `task-${index + 1}`,
+          title,
+          dependsOnTaskIds: [],
+          outputTarget: null,
+        };
+      }
+      if (!row || typeof row !== "object") return null;
+      const title = String(row?.title || row?.task || row?.content || "").trim();
+      if (title.length < 6) return null;
+      const rawId = String(row?.id || row?.task_id || row?.taskId || `task-${index + 1}`).trim();
+      const id = rawId || `task-${index + 1}`;
+      const dependencySource = Array.isArray(row?.depends_on_task_ids)
+        ? row.depends_on_task_ids
+        : Array.isArray(row?.dependsOnTaskIds)
+          ? row.dependsOnTaskIds
+          : Array.isArray(row?.dependsOn)
+            ? row.dependsOn
+            : Array.isArray(row?.dependencies)
+              ? row.dependencies
+              : [];
+      const dependsOnTaskIds = dependencySource
+        .map((dep) => String(dep || "").trim())
+        .filter(Boolean);
+      const outputTarget = normalizeOutputTarget(
+        row?.output_target || row?.outputTarget || row?.artifact || row?.target_file || null
+      );
+      return {
+        id,
+        title,
+        dependsOnTaskIds,
+        outputTarget,
+        taskKind: normalizeTaskKind(row?.task_kind || row?.taskKind || row?.kind, outputTarget),
+      };
+    })
+    .filter(Boolean)
+    .slice(0, normalizedMax);
+  const withUniqueIds = [];
+  const idCounts = new Map();
+  for (const row of provisional) {
+    const base = String(row?.id || "task").trim() || "task";
+    const count = Number(idCounts.get(base) || 0) + 1;
+    idCounts.set(base, count);
+    const uniqueId = count > 1 ? `${base}-${count}` : base;
+    withUniqueIds.push({
+      id: uniqueId,
+      title: String(row?.title || "").trim(),
+      dependsOnTaskIds: Array.isArray(row?.dependsOnTaskIds) ? row.dependsOnTaskIds : [],
+      outputTarget: row?.outputTarget || null,
+      taskKind: String(row?.taskKind || "").trim() || "inspection",
     });
+  }
+  const knownIds = new Set(withUniqueIds.map((row) => row.id));
+  return withUniqueIds.map((row, index) => {
+    let dependsOnTaskIds = (Array.isArray(row?.dependsOnTaskIds) ? row.dependsOnTaskIds : [])
+      .map((dep) => String(dep || "").trim())
+      .filter((dep) => dep && dep !== row.id && knownIds.has(dep));
+    if (!dependsOnTaskIds.length && linearFallback && index > 0) {
+      dependsOnTaskIds = [withUniqueIds[index - 1].id];
+    }
+    return {
+      id: row.id,
+      title: row.title,
+      dependsOnTaskIds,
+      outputTarget: row?.outputTarget || null,
+      taskKind: String(row?.taskKind || "").trim() || "inspection",
+    };
   });
 }
 
-async function handleSwarmApi(req, res, session) {
-  const pathname = new URL(req.url, `http://127.0.0.1:${PORTAL_PORT}`).pathname;
-
-  if (pathname === "/api/swarm/status" && req.method === "GET") {
-    sendJson(res, 200, {
-      ok: true,
-      status: swarmState.status,
-      objective: swarmState.objective,
-      workspaceRoot: swarmState.workspaceRoot,
-      maxTasks: swarmState.maxTasks,
-      startedAt: swarmState.startedAt,
-      stoppedAt: swarmState.stoppedAt,
-      localEngine: isLocalEngineUrl(ENGINE_URL),
-      lastError: swarmState.lastError || null,
-    });
-    return true;
+function inferOutputTargetFromText(text) {
+  const source = String(text || "").trim();
+  if (!source) return null;
+  const backtickMatch = source.match(/`([^`\n]+?\.[A-Za-z0-9_-]{1,12})`/);
+  if (backtickMatch?.[1]) {
+    return {
+      path: backtickMatch[1].trim(),
+      kind: "artifact",
+      operation: "create_or_update",
+    };
   }
+  const saveAsMatch = source.match(/\bsave as\s+([A-Za-z0-9_./-]+\.[A-Za-z0-9_-]{1,12})\b/i);
+  if (saveAsMatch?.[1]) {
+    return {
+      path: saveAsMatch[1].trim(),
+      kind: "artifact",
+      operation: "create_or_update",
+    };
+  }
+  return null;
+}
 
-  if (pathname === "/api/swarm/start" && req.method === "POST") {
+function ensurePlannerTaskOutputTargets(tasks, objective) {
+  const list = Array.isArray(tasks) ? tasks : [];
+  return list.map((task) => {
+    const taskKind = String(task?.taskKind || "").trim().toLowerCase() || "inspection";
+    const existing = task?.outputTarget && typeof task.outputTarget === "object" ? task.outputTarget : null;
+    return {
+      ...task,
+      taskKind,
+      outputTarget: existing || null,
+    };
+  });
+}
+
+function validateStrictPlannerTasks(tasks) {
+  const list = Array.isArray(tasks) ? tasks : [];
+  const invalidTaskKinds = list
+    .filter((task) => !["implementation", "inspection", "research", "validation"].includes(String(task?.taskKind || "").trim().toLowerCase()))
+    .map((task) => String(task?.id || task?.title || "task").trim())
+    .filter(Boolean);
+  const missing = list
+    .filter((task) => {
+      const taskKind = String(task?.taskKind || "").trim().toLowerCase();
+      return taskKind === "implementation" && !String(task?.outputTarget?.path || "").trim();
+    })
+    .map((task) => String(task?.id || task?.title || "task").trim())
+    .filter(Boolean);
+  return {
+    ok: missing.length === 0 && invalidTaskKinds.length === 0,
+    missing,
+    invalidTaskKinds,
+  };
+}
+
+function parsePlanTasksFromAssistant(assistantText, maxTasks = 8, options = {}) {
+  const normalizedMax = Math.max(1, Number(maxTasks) || 8);
+  const allowTextFallback = options?.allowTextFallback !== false;
+  const fencedJson = String(assistantText || "").match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidateJson = (fencedJson?.[1] || String(assistantText || "")).trim();
+  const parsedTodos = (() => {
     try {
-      const body = await readJsonBody(req);
-      startSwarm(session, body || {});
-      sendJson(res, 200, { ok: true });
-    } catch (e) {
-      sendJson(res, 400, { ok: false, error: e instanceof Error ? e.message : String(e) });
+      const payload = JSON.parse(candidateJson);
+      if (Array.isArray(payload)) return payload;
+      if (Array.isArray(payload?.tasks)) return payload.tasks;
+      if (Array.isArray(payload?.plan)) return payload.plan;
+      if (Array.isArray(payload?.steps)) return payload.steps;
+      if (Array.isArray(payload?.items)) return payload.items;
+      return [];
+    } catch {
+      return [];
     }
-    return true;
-  }
+  })();
+  const fromJson = normalizePlannerTasks(parsedTodos, normalizedMax, { linearFallback: false });
+  if (fromJson.length) return fromJson;
+  if (!allowTextFallback) return [];
+  const fromText = String(assistantText || "")
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^[-*#\d\.\)\[\]\s]+/, "").trim())
+    .filter((line) => line.length >= 6)
+    .slice(0, normalizedMax);
+  return normalizePlannerTasks(fromText, normalizedMax, { linearFallback: true });
+}
 
-  if (pathname === "/api/swarm/stop" && req.method === "POST") {
-    stopSwarm();
-    sendJson(res, 200, { ok: true, status: swarmState.status });
-    return true;
+function extractPlannerFailureText(text) {
+  const value = String(text || "").trim();
+  if (!value) return "";
+  const firstLine = value.split(/\r?\n/, 1)[0] || "";
+  const normalized = firstLine.toUpperCase();
+  if (normalized.startsWith("ENGINE_ERROR:")) return value;
+  if (
+    normalized.includes("AUTHENTICATION_ERROR") ||
+    normalized.includes("RATE_LIMIT_EXCEEDED") ||
+    normalized.includes("CONTEXT_LENGTH_EXCEEDED") ||
+    normalized.includes("PROVIDER_SERVER_ERROR") ||
+    normalized.includes("PROVIDER_REQUEST_FAILED")
+  ) {
+    return value;
   }
+  if (/key limit exceeded|403 forbidden|monthly limit|rate limit/i.test(value)) {
+    return value;
+  }
+  return "";
+}
 
-  if (pathname === "/api/swarm/snapshot" && req.method === "GET") {
-    const registry = await readSwarmRegistry(session.token);
-    sendJson(res, 200, {
-      ok: true,
-      status: swarmState.status,
-      registry,
-      logs: swarmState.logs.slice(-300),
-      reasons: swarmState.reasons.slice(-250),
-      startedAt: swarmState.startedAt,
-      stoppedAt: swarmState.stoppedAt,
-      lastError: swarmState.lastError || null,
-      localEngine: isLocalEngineUrl(ENGINE_URL),
-    });
-    return true;
+function fallbackPlannerTasks(objective, maxTasks = 8, assistantText = "") {
+  const fromAssistantText = parsePlanTasksFromAssistant(assistantText, maxTasks, {
+    allowTextFallback: true,
+  });
+  if (fromAssistantText.length) {
+    return {
+      source: "llm_text_recovery",
+      note: "Recovered planner tasks from non-JSON assistant text.",
+      tasks: fromAssistantText,
+    };
+  }
+  const fromObjective = normalizePlannerTasks(parseObjectiveTodos(objective, maxTasks), maxTasks, {
+    linearFallback: true,
+  });
+  if (fromObjective.length) {
+    return {
+      source: "local_objective_parser",
+      note: "Synthesized planner tasks from the objective after planner failure.",
+      tasks: fromObjective,
+    };
   }
+  return {
+    source: "local_single_task_fallback",
+    note: "Synthesized a single fallback task after planner failure.",
+    tasks: normalizePlannerTasks(["Execute requested objective"], 1, {
+      linearFallback: false,
+    }),
+  };
+}
 
-  if (pathname === "/api/swarm/events" && req.method === "GET") {
-    res.writeHead(200, {
-      "content-type": "text/event-stream",
-      "cache-control": "no-cache",
-      connection: "keep-alive",
-    });
-    res.write(`data: ${JSON.stringify({ kind: "hello", ts: Date.now(), status: swarmState.status })}\n\n`);
-    swarmSseClients.add(res);
-    req.on("close", () => swarmSseClients.delete(res));
-    return true;
+async function generatePlanTodosWithLLM(session, run, maxTasks) {
+  const runId = String(run?.run_id || "").trim();
+  if (!runId) throw new Error("Missing run id for plan generation.");
+  const sessionId = await createExecutionSession(session, run);
+  const prompt = [
+    "You are planning a swarm run.",
+    "",
+    `Objective: ${String(run?.objective || "").trim()}`,
+    `Workspace: ${String(run?.workspace?.canonical_path || "").trim()}`,
+    "",
+    `Generate ${Math.max(1, Number(maxTasks) || 3)} concise, execution-ready tasks.`,
+    "If the objective requires creating or updating a single file, prefer ONE implementation task that creates the complete file.",
+    "Do not split creation and refinement of the same artifact into separate dependent tasks.",
+    "Inspection tasks should only exist when the workspace has existing files that must be understood first.",
+    "For greenfield or nearly empty workspaces, skip inspection and go straight to implementation.",
+    "Return strict JSON only in this shape:",
+    '{"tasks":[{"id":"task-1","title":"...","task_kind":"inspection","depends_on_task_ids":[]},{"id":"task-2","title":"...","task_kind":"implementation","depends_on_task_ids":["task-1"],"output_target":{"path":"relative/path.ext","kind":"source|spec|config|document|test|asset","operation":"create|update|create_or_update"}}]}',
+    "Use depends_on_task_ids only when a task requires outputs from another task.",
+    "Independent tasks must have an empty depends_on_task_ids array.",
+    "Every task must include task_kind: implementation, inspection, research, or validation.",
+    "Only implementation tasks must include output_target.path naming the concrete workspace file or artifact to create or update.",
+    "Inspection/research tasks are read-only and should not require file writes.",
+    "Keep output_target generic and file-type agnostic: Python, JS, HTML, Markdown, TOML, YAML, text, tests, and assets are all valid.",
+    "Do not include explanations.",
+  ].join("\n");
+  const promptResponse = await engineRequestJson(
+    session,
+    `/session/${encodeURIComponent(sessionId)}/prompt_sync`,
+    {
+      method: "POST",
+      timeoutMs: 3 * 60 * 1000,
+      body: {
+        parts: [{ type: "text", text: prompt }],
+      },
+    }
+  );
+  const syncRows = Array.isArray(promptResponse) ? promptResponse : [];
+  const fromSync = extractAssistantText(syncRows);
+  const syncFailure = extractPlannerFailureText(fromSync);
+  if (syncFailure) {
+    const error = new Error(syncFailure);
+    error.sessionId = sessionId;
+    throw error;
+  }
+  if (fromSync) {
+    return {
+      sessionId,
+      tasks: parsePlanTasksFromAssistant(fromSync, maxTasks, { allowTextFallback: false }),
+      assistantText: fromSync,
+    };
   }
+  const sessionSnapshot = await engineRequestJson(
+    session,
+    `/session/${encodeURIComponent(sessionId)}`
+  ).catch(() => null);
+  const messages = Array.isArray(sessionSnapshot?.messages) ? sessionSnapshot.messages : [];
+  const fromSnapshot = extractAssistantText(messages);
+  const snapshotFailure = extractPlannerFailureText(fromSnapshot);
+  if (snapshotFailure) {
+    const error = new Error(snapshotFailure);
+    error.sessionId = sessionId;
+    throw error;
+  }
+  return {
+    sessionId,
+    tasks: parsePlanTasksFromAssistant(fromSnapshot, maxTasks, { allowTextFallback: false }),
+    assistantText: fromSnapshot,
+  };
+}
 
-  return false;
+function isRunTerminal(status) {
+  const normalized = String(status || "")
+    .trim()
+    .toLowerCase();
+  return ["completed", "failed", "cancelled"].includes(normalized);
 }
 
+async function seedContextRunSteps(session, runId, objective) {
+  const todoRows = parseObjectiveTodos(objective, 8).map((content, idx) => ({
+    id: `step-${idx + 1}`,
+    content,
+    status: "pending",
+  }));
+  await engineRequestJson(session, `/context/runs/${encodeURIComponent(runId)}/todos/sync`, {
+    method: "POST",
+    body: {
+      replace: true,
+      todos: todoRows,
+      source_session_id: null,
+      source_run_id: runId,
+    },
+  });
+}
+
+async function seedContextRunStepsFromTitles(session, runId, titles = []) {
+  const todoRows = (Array.isArray(titles) ? titles : [])
+    .map((row) => String(row || "").trim())
+    .filter((row) => row.length >= 3)
+    .map((content, idx) => ({
+      id: `step-${idx + 1}`,
+      content,
+      status: "pending",
+    }));
+  if (!todoRows.length) {
+    throw new Error("No valid todo rows for context step seeding.");
+  }
+  await engineRequestJson(session, `/context/runs/${encodeURIComponent(runId)}/todos/sync`, {
+    method: "POST",
+    body: {
+      replace: true,
+      todos: todoRows,
+      source_session_id: null,
+      source_run_id: runId,
+    },
+  });
+  return todoRows.length;
+}
+
+async function createExecutionSession(session, run) {
+  const runId = String(run?.run_id || "").trim();
+  const controller = getSwarmRunController(runId);
+  const workspaceCandidates = [
+    run?.workspace?.canonical_path,
+    run?.workspace?.workspace_root,
+    run?.workspace_root,
+    controller?.workspaceRoot,
+    controller?.repoRoot,
+    swarmState.workspaceRoot,
+    swarmState.repoRoot,
+    REPO_ROOT,
+  ];
+  const workspaceRootRaw = workspaceCandidates
+    .map((value) => String(value || "").trim())
+    .find((value) => value.length > 0);
+  const workspaceRoot = await workspaceExistsAsDirectory(workspaceRootRaw || REPO_ROOT);
+  if (!workspaceRoot) {
+    throw new Error(
+      `Workspace root does not exist or is not a directory: ${resolve(String(workspaceRootRaw || REPO_ROOT))}`
+    );
+  }
+  const resolved = await resolveExecutionModel(session, run);
+  const modelProvider = resolved.provider;
+  const modelId = resolved.model;
+  upsertSwarmRunController(runId, {
+    resolvedModelProvider: modelProvider,
+    resolvedModelId: modelId,
+    modelResolutionSource: resolved.source,
+    modelProvider,
+    modelId,
+  });
+  const payload = await engineRequestJson(session, "/session", {
+    method: "POST",
+    body: {
+      title: `Swarm ${String(run?.run_id || "").trim()}`,
+      directory: workspaceRoot,
+      workspace_root: workspaceRoot,
+      permission: [
+        { permission: "write", pattern: "*", action: "allow" },
+        { permission: "edit", pattern: "*", action: "allow" },
+        { permission: "apply_patch", pattern: "*", action: "allow" },
+        { permission: "read", pattern: "*", action: "allow" },
+        { permission: "glob", pattern: "*", action: "allow" },
+        { permission: "search", pattern: "*", action: "allow" },
+        { permission: "grep", pattern: "*", action: "allow" },
+        { permission: "codesearch", pattern: "*", action: "allow" },
+        { permission: "ls", pattern: "*", action: "allow" },
+        { permission: "list", pattern: "*", action: "allow" },
+        { permission: "todowrite", pattern: "*", action: "allow" },
+        { permission: "todo_write", pattern: "*", action: "allow" },
+        { permission: "update_todo_list", pattern: "*", action: "allow" },
+        { permission: "websearch", pattern: "*", action: "allow" },
+        { permission: "webfetch", pattern: "*", action: "allow" },
+        { permission: "webfetch_html", pattern: "*", action: "allow" },
+        { permission: "bash", pattern: "*", action: "deny" },
+        { permission: "task", pattern: "*", action: "deny" },
+        { permission: "spawn_agent", pattern: "*", action: "deny" },
+        { permission: "batch", pattern: "*", action: "deny" },
+      ],
+      provider: modelProvider || undefined,
+      model:
+        modelProvider && modelId
+          ? {
+              providerID: modelProvider,
+              modelID: modelId,
+            }
+          : undefined,
+    },
+  });
+  return String(payload?.id || "").trim();
+}
+
+function workerExecutionToolAllowlist() {
+  return [
+    "ls",
+    "list",
+    "glob",
+    "search",
+    "grep",
+    "codesearch",
+    "read",
+    "write",
+    "edit",
+    "apply_patch",
+  ];
+}
+
+function workerWriteRetryToolAllowlist() {
+  return ["write", "edit", "apply_patch"];
+}
+
+function strictWriteRetryEnabled() {
+  const raw = String(process.env.TANDEM_STRICT_WRITE_RETRY_ENABLED || "").trim().toLowerCase();
+  if (!raw) return true;
+  return !["0", "false", "no", "off"].includes(raw);
+}
+
+function strictWriteRetryMaxAttempts() {
+  const parsed = Number.parseInt(
+    String(process.env.TANDEM_STRICT_WRITE_RETRY_MAX_ATTEMPTS || "3"),
+    10
+  );
+  return Number.isFinite(parsed) ? Math.max(1, parsed) : 3;
+}
+
+function nonWritingRetryMaxAttempts() {
+  const parsed = Number.parseInt(
+    String(process.env.TANDEM_NON_WRITING_RETRY_MAX_ATTEMPTS || "2"),
+    10
+  );
+  return Number.isFinite(parsed) ? Math.max(1, parsed) : 2;
+}
+
+function classifyStrictWriteFailureReason(verification) {
+  const reason = String(verification?.reason || "").trim().toUpperCase();
+  if (!reason || reason === "VERIFIED") return "";
+  if (
+    reason === "WRITE_ARGS_EMPTY_FROM_PROVIDER" ||
+    reason === "WRITE_ARGS_UNPARSEABLE_FROM_PROVIDER" ||
+    reason === "FILE_PATH_MISSING" ||
+    reason === "WRITE_CONTENT_MISSING"
+  ) {
+    return "malformed_write_args";
+  }
+  if (
+    reason === "NO_WRITE_ACTIVITY_NO_WORKSPACE_CHANGE" ||
+    reason === "WRITE_REQUIRED_NOT_SATISFIED" ||
+    reason === "WRITE_TOOL_ATTEMPT_REJECTED_NO_WORKSPACE_CHANGE"
+  ) {
+    return "write_required_unsatisfied";
+  }
+  if (
+    reason === "TOOL_ATTEMPT_REJECTED_NO_WORKSPACE_CHANGE" ||
+    reason === "NO_TOOL_ACTIVITY_NO_WORKSPACE_CHANGE"
+  ) {
+    return "no_workspace_change";
+  }
+  return "";
+}
+
+function buildStrictWriteRetryRequest(prompt, verification, attemptIndex, maxAttempts) {
+  const failureClass = classifyStrictWriteFailureReason(verification);
+  const needsInspection =
+    Number(verification?.total_tool_calls || 0) === 0 &&
+    Number(verification?.rejected_tool_calls || 0) === 0;
+  const recoveryLines = [
+    prompt,
+    "",
+    "[Strict Write Recovery]",
+    `Attempt ${attemptIndex}/${maxAttempts} failed with ${failureClass || "strict_write_failure"}.`,
+    "- You must satisfy strict write mode on this retry.",
+    '- Valid write shape: {"path":"target-file","content":"full file contents"}',
+    "- For file tools, include a non-empty `path` string.",
+    "- For `write`, include a non-empty `content` string.",
+    "- Do not use bash.",
+  ];
+  if (needsInspection) {
+    recoveryLines.push("- Use tools on this retry.");
+    recoveryLines.push("- Inspect minimally with ls/list/glob/search/read if needed.");
+    recoveryLines.push("- Then create or modify the required file in the same turn.");
+  } else {
+    recoveryLines.push("- Do not inspect further with read/search/glob/ls/list.");
+    recoveryLines.push("- Create or modify the required target directly with write/edit/apply_patch.");
+  }
+  return {
+    parts: [{ type: "text", text: recoveryLines.join("\n") }],
+    tool_mode: "required",
+    tool_allowlist: needsInspection
+      ? workerExecutionToolAllowlist()
+      : workerWriteRetryToolAllowlist(),
+    write_required: true,
+  };
+}
+
+function classifyNonWritingFailureReason(verification) {
+  const reason = String(verification?.reason || "").trim().toUpperCase();
+  if (!reason || reason === "VERIFIED") return "";
+  if (reason === "NO_TOOL_ACTIVITY_NO_DECISION" || reason === "NO_TOOL_ACTIVITY") {
+    return "no_tool_activity";
+  }
+  if (reason === "DECISION_PAYLOAD_MISSING") return "decision_payload_missing";
+  return "non_writing_verification_failed";
+}
+
+function buildNonWritingRetryRequest(prompt, verification, attemptIndex, maxAttempts) {
+  const failureClass = classifyNonWritingFailureReason(verification);
+  const hasToolCalls =
+    Number(verification?.total_tool_calls || 0) > 0 ||
+    Number(verification?.rejected_tool_calls || 0) > 0;
+  const recoveryLines = [
+    prompt,
+    "",
+    "[Non-Writing Recovery]",
+    `Attempt ${attemptIndex}/${maxAttempts} failed with ${failureClass || "verification_failed"}.`,
+    "- This task is read-only and must use tools.",
+    "- Allowed tools: ls, list, glob, search, grep, codesearch, read.",
+    "- Do not call write/edit/apply_patch for this task.",
+    '- Return strict JSON only: {"decision":{"summary":"...","evidence":["..."],"output_target":{"path":"...","kind":"artifact","operation":"create_or_update"}}}.',
+  ];
+  if (!hasToolCalls) {
+    recoveryLines.push("- Execute at least one read-only tool call before finalizing.");
+    recoveryLines.push("- Keep tool usage minimal and directly relevant to the task.");
+  } else {
+    recoveryLines.push("- You already used tools; now return the required JSON decision payload.");
+    recoveryLines.push("- Ensure the response is valid JSON and includes decision.summary.");
+  }
+  return {
+    parts: [{ type: "text", text: recoveryLines.join("\n") }],
+    tool_mode: "required",
+    tool_allowlist: ["ls", "list", "glob", "search", "grep", "codesearch", "read"],
+  };
+}
+
+const WRITE_TOOL_NAMES = new Set(["write", "edit", "apply_patch"]);
+const REQUIRED_TOOL_MODE_REASON = "TOOL_MODE_REQUIRED_NOT_SATISFIED";
+const REQUIRED_TOOL_REASON_PATTERN = new RegExp(
+  `${REQUIRED_TOOL_MODE_REASON}:\\s*([A-Z_]+)\\b`
+);
+
+function normalizeVerificationMode(mode) {
+  return String(mode || "")
+    .trim()
+    .toLowerCase() === "lenient"
+    ? "lenient"
+    : "strict";
+}
+
+function normalizeToolName(tool) {
+  const raw = String(tool || "")
+    .trim()
+    .toLowerCase();
+  if (!raw) return "";
+  const parts = raw.split(":").filter(Boolean);
+  return parts.length ? parts[parts.length - 1] : raw;
+}
+
+function isWriteToolName(tool) {
+  return WRITE_TOOL_NAMES.has(normalizeToolName(tool));
+}
+
+function createExecutionError(message, details = {}) {
+  const error = new Error(message);
+  if (details?.sessionId) error.sessionId = String(details.sessionId || "").trim();
+  if (details?.verification && typeof details.verification === "object") {
+    error.verification = details.verification;
+  }
+  return error;
+}
+
+function normalizeWorkspaceRelativePath(pathname) {
+  return String(pathname || "")
+    .replace(/\\/g, "/")
+    .replace(/^\.?\//, "")
+    .replace(/^\/+/, "")
+    .trim();
+}
+
+function extractRequiredToolFailureReason(text) {
+  const raw = String(text || "").trim();
+  if (!raw) return "";
+  const match = raw.match(REQUIRED_TOOL_REASON_PATTERN);
+  return String(match?.[1] || "").trim().toUpperCase();
+}
+
+function shouldTrackWorkspacePath(pathname) {
+  const normalized = normalizeWorkspaceRelativePath(pathname);
+  return (
+    !!normalized &&
+    normalized !== ".git" &&
+    normalized !== ".tandem" &&
+    !normalized.startsWith(".git/") &&
+    !normalized.startsWith(".tandem/") &&
+    !normalized.startsWith(".swarm/") &&
+    !normalized.startsWith("node_modules/") &&
+    !normalized.startsWith("dist/") &&
+    !normalized.startsWith("target/")
+  );
+}
+
+async function fingerprintWorkspaceFile(pathname) {
+  const info = await stat(pathname).catch(() => null);
+  if (!info?.isFile()) return null;
+  let contentHash = "";
+  if (Number(info.size || 0) <= 1024 * 1024) {
+    const bytes = await readFile(pathname).catch(() => null);
+    if (bytes) {
+      contentHash = createHash("sha1").update(bytes).digest("hex");
+    }
+  }
+  return {
+    size: Number(info.size || 0),
+    modifiedMs: Number(info.mtimeMs || 0),
+    contentHash,
+  };
+}
+
+function parseGitStatusEntries(output) {
+  const chunks = String(output || "").split("\0");
+  const entries = [];
+  for (let index = 0; index < chunks.length; index += 1) {
+    const chunk = String(chunks[index] || "");
+    if (!chunk) continue;
+    const status = chunk.slice(0, 2);
+    const primaryPath = normalizeWorkspaceRelativePath(chunk.slice(3));
+    if (status.startsWith("R") || status.startsWith("C")) {
+      const renamedPath = normalizeWorkspaceRelativePath(chunks[index + 1] || "");
+      if (!renamedPath && !primaryPath) continue;
+      entries.push({
+        status,
+        path: renamedPath || primaryPath,
+        originalPath: primaryPath || "",
+      });
+      index += 1;
+      continue;
+    }
+    if (!primaryPath) continue;
+    entries.push({
+      status,
+      path: primaryPath,
+      originalPath: "",
+    });
+  }
+  return entries;
+}
+
+function buildGitStatusIndex(entries) {
+  const statusByPath = Object.create(null);
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    const rawStatus = String(entry?.status || "")
+      .trim()
+      .toUpperCase();
+    let normalized = "M";
+    if (rawStatus === "??") normalized = "A";
+    else if (rawStatus.startsWith("R") || rawStatus.startsWith("C"))
+      normalized = rawStatus.slice(0, 1);
+    else if (rawStatus.includes("D")) normalized = "D";
+    else if (rawStatus.includes("A")) normalized = "A";
+    if (entry?.originalPath && shouldTrackWorkspacePath(entry.originalPath)) {
+      statusByPath[normalizeWorkspaceRelativePath(entry.originalPath)] = "D";
+    }
+    if (entry?.path && shouldTrackWorkspacePath(entry.path)) {
+      statusByPath[normalizeWorkspaceRelativePath(entry.path)] = normalized;
+    }
+  }
+  return statusByPath;
+}
+
+function collectWorkspaceSnapshotSeedPaths(includePaths = []) {
+  return Array.from(
+    new Set(
+      (Array.isArray(includePaths) ? includePaths : [])
+        .map((pathname) => normalizeWorkspaceRelativePath(pathname))
+        .filter((pathname) => shouldTrackWorkspacePath(pathname))
+    )
+  ).sort((a, b) => a.localeCompare(b));
+}
+
+async function captureGitWorkspaceSnapshot(workspaceRoot, includePaths = []) {
+  const repo = await isGitRepo(workspaceRoot);
+  if (!repo?.ok || !repo.root) return null;
+  const gitStatus = await runGit(
+    ["-C", repo.root, "status", "--porcelain=v1", "--untracked-files=all", "-z"],
+    {
+      stdio: "pipe",
+      safeDirectory: repo.root,
+    }
+  ).catch(() => null);
+  if (!gitStatus) return null;
+  const entries = parseGitStatusEntries(gitStatus.stdout || "");
+  const files = Object.create(null);
+  const candidatePaths = collectWorkspaceSnapshotSeedPaths([
+    ...entries.flatMap((entry) => [entry?.path || "", entry?.originalPath || ""]),
+    ...includePaths,
+  ]);
+  for (const relativePath of candidatePaths) {
+    const fingerprint = await fingerprintWorkspaceFile(join(repo.root, relativePath));
+    if (fingerprint) files[relativePath] = fingerprint;
+  }
+  return {
+    mode: "git_status",
+    root: repo.root,
+    files,
+    statusByPath: buildGitStatusIndex(entries),
+  };
+}
+
+async function captureWorkspaceSnapshot(workspaceRoot, options = {}) {
+  const root = await workspaceExistsAsDirectory(workspaceRoot);
+  if (!root) {
+    throw new Error(
+      `Workspace snapshot root not found: ${resolve(String(workspaceRoot || REPO_ROOT))}`
+    );
+  }
+  const includePaths = collectWorkspaceSnapshotSeedPaths(options?.includePaths);
+  const gitSnapshot = await captureGitWorkspaceSnapshot(root, includePaths);
+  if (gitSnapshot) return gitSnapshot;
+  const files = Object.create(null);
+  async function walk(dirPath) {
+    const entries = await readdir(dirPath, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      const absolutePath = join(dirPath, entry.name);
+      const relativePath = normalizeWorkspaceRelativePath(relative(root, absolutePath));
+      if (!shouldTrackWorkspacePath(relativePath)) continue;
+      if (entry.isDirectory()) {
+        await walk(absolutePath);
+        continue;
+      }
+      if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+      const fingerprint = await fingerprintWorkspaceFile(absolutePath);
+      if (fingerprint) files[relativePath] = fingerprint;
+    }
+  }
+  await walk(root);
+  return {
+    mode: "filesystem_fingerprint",
+    root,
+    files,
+    statusByPath: Object.create(null),
+  };
+}
+
+function summarizeWorkspaceChanges(beforeSnapshot, afterSnapshot) {
+  const beforeFiles =
+    beforeSnapshot?.files && typeof beforeSnapshot.files === "object" ? beforeSnapshot.files : {};
+  const afterFiles =
+    afterSnapshot?.files && typeof afterSnapshot.files === "object" ? afterSnapshot.files : {};
+  const beforeStatusByPath =
+    beforeSnapshot?.statusByPath && typeof beforeSnapshot.statusByPath === "object"
+      ? beforeSnapshot.statusByPath
+      : {};
+  const afterStatusByPath =
+    afterSnapshot?.statusByPath && typeof afterSnapshot.statusByPath === "object"
+      ? afterSnapshot.statusByPath
+      : {};
+  const created = [];
+  const updated = [];
+  const deleted = [];
+  const allPaths = new Set([
+    ...Object.keys(beforeFiles),
+    ...Object.keys(afterFiles),
+    ...Object.keys(beforeStatusByPath),
+    ...Object.keys(afterStatusByPath),
+  ]);
+  for (const pathname of Array.from(allPaths)) {
+    const beforeFingerprint = beforeFiles[pathname];
+    const afterFingerprint = afterFiles[pathname];
+    const afterStatus = String(afterStatusByPath[pathname] || "")
+      .trim()
+      .toUpperCase();
+    const beforeStatus = String(beforeStatusByPath[pathname] || "")
+      .trim()
+      .toUpperCase();
+    if (!beforeFingerprint && !afterFingerprint) {
+      if (afterStatus === "D") deleted.push(pathname);
+      else if (afterStatus || beforeStatus) updated.push(pathname);
+      continue;
+    }
+    if (!beforeFingerprint && afterFingerprint) {
+      if (afterStatus === "A" || afterStatus === "C" || afterStatus === "R") created.push(pathname);
+      else updated.push(pathname);
+      continue;
+    }
+    if (beforeFingerprint && !afterFingerprint) {
+      deleted.push(pathname);
+      continue;
+    }
+    if (
+      Number(beforeFingerprint?.size || 0) !== Number(afterFingerprint?.size || 0) ||
+      Number(beforeFingerprint?.modifiedMs || 0) !== Number(afterFingerprint?.modifiedMs || 0) ||
+      String(beforeFingerprint?.contentHash || "") !== String(afterFingerprint?.contentHash || "")
+    ) {
+      updated.push(pathname);
+    }
+  }
+  created.sort((a, b) => a.localeCompare(b));
+  updated.sort((a, b) => a.localeCompare(b));
+  deleted.sort((a, b) => a.localeCompare(b));
+  const lines = [
+    `Workspace changes: ${created.length} created, ${updated.length} updated, ${deleted.length} deleted`,
+    ...created.slice(0, 20).map((pathname) => `+ ${pathname}`),
+    ...updated.slice(0, 40).map((pathname) => `~ ${pathname}`),
+    ...deleted.slice(0, 20).map((pathname) => `- ${pathname}`),
+  ];
+  return {
+    mode: String(afterSnapshot?.mode || beforeSnapshot?.mode || "unknown"),
+    hasChanges: created.length > 0 || updated.length > 0 || deleted.length > 0,
+    created,
+    updated,
+    deleted,
+    paths: [...created, ...updated, ...deleted],
+    summary: lines.join("\n"),
+  };
+}
+
+function emptyToolActivityAudit(source = "") {
+  return {
+    source: source || "",
+    totalToolCalls: 0,
+    writeToolCalls: 0,
+    rejectedToolCalls: 0,
+    rejectedWriteToolCalls: 0,
+    toolNames: [],
+    rejectedToolNames: [],
+    rejectionReasons: [],
+  };
+}
+
+function extractToolFailureSignalsFromText(text) {
+  const raw = String(text || "").trim();
+  if (!raw) return [];
+  const failures = [];
+  const knownReasons = [
+    "FILE_PATH_MISSING",
+    "WRITE_CONTENT_MISSING",
+    "WRITE_ARGS_EMPTY_FROM_PROVIDER",
+    "WRITE_ARGS_UNPARSEABLE_FROM_PROVIDER",
+    "WEBFETCH_URL_MISSING",
+    "WEBSEARCH_QUERY_MISSING",
+    "BASH_COMMAND_MISSING",
+    "PACK_BUILDER_PLAN_ID_MISSING",
+    "PACK_BUILDER_GOAL_MISSING",
+    "TOOL_ARGUMENTS_MISSING",
+  ];
+  for (const reason of knownReasons) {
+    if (raw.includes(reason)) failures.push({ tool: "", reason });
+  }
+  for (const match of raw.matchAll(/Permission denied for tool `([^`]+)`/g)) {
+    failures.push({ tool: match[1], reason: "PERMISSION_DENIED" });
+  }
+  for (const match of raw.matchAll(/Tool `([^`]+)` is not allowed/g)) {
+    failures.push({ tool: match[1], reason: "TOOL_NOT_ALLOWED" });
+  }
+  for (const tool of ["read", "write", "edit", "apply_patch", "glob", "list", "ls"]) {
+    const failedPattern = new RegExp(`(?:\`|\\b)${tool}(?:\`|\\b)[^\\n.]{0,120}\\bfailed\\b`, "i");
+    if (failedPattern.test(raw)) {
+      failures.push({ tool, reason: "TOOL_CALL_FAILED" });
+    }
+  }
+  return failures;
+}
+
+function collectToolActivity(rows, source = "") {
+  if (!Array.isArray(rows)) return emptyToolActivityAudit(source);
+  const toolNames = new Set();
+  const rejectedToolNames = new Set();
+  const rejectionReasons = new Set();
+  let totalToolCalls = 0;
+  let writeToolCalls = 0;
+  let rejectedToolCalls = 0;
+  let rejectedWriteToolCalls = 0;
+  const recordTool = (tool, options = {}) => {
+    const normalized = normalizeToolName(tool) || "tool";
+    const rejected = options?.rejected === true;
+    const reason = String(options?.reason || "").trim();
+    if (rejected) {
+      rejectedToolCalls += 1;
+      rejectedToolNames.add(normalized);
+      if (isWriteToolName(normalized)) rejectedWriteToolCalls += 1;
+      if (reason) rejectionReasons.add(reason);
+      return;
+    }
+    totalToolCalls += 1;
+    toolNames.add(normalized);
+    if (isWriteToolName(normalized)) writeToolCalls += 1;
+  };
+  for (const row of rows) {
+    const parts = Array.isArray(row?.parts) ? row.parts : [];
+    let rowRecorded = false;
+    for (const part of parts) {
+      const partType = String(part?.type || part?.part_type || "")
+        .trim()
+        .toLowerCase();
+      const partTool = String(part?.tool || part?.name || "").trim();
+      if (!partType.includes("tool") && !partTool) continue;
+      const rejected =
+        String(part?.state || "")
+          .trim()
+          .toLowerCase() === "failed" || !!String(part?.error || "").trim();
+      recordTool(partTool, {
+        rejected,
+        reason: String(part?.error || "").trim(),
+      });
+      rowRecorded = true;
+    }
+    if (!rowRecorded) {
+      const rowType = String(row?.type || "")
+        .trim()
+        .toLowerCase();
+      const rowTool = String(row?.tool || row?.name || "").trim();
+      if (rowType.includes("tool") || rowTool) {
+        const rejected =
+          String(row?.state || "")
+            .trim()
+            .toLowerCase() === "failed" || !!String(row?.error || "").trim();
+        recordTool(rowTool, {
+          rejected,
+          reason: String(row?.error || "").trim(),
+        });
+        rowRecorded = true;
+      }
+    }
+    if (rowRecorded) continue;
+    for (const failure of extractToolFailureSignalsFromText(textOfMessage(row))) {
+      recordTool(failure.tool, {
+        rejected: true,
+        reason: failure.reason,
+      });
+    }
+  }
+  return {
+    source: source || "",
+    totalToolCalls,
+    writeToolCalls,
+    rejectedToolCalls,
+    rejectedWriteToolCalls,
+    toolNames: Array.from(toolNames).sort((a, b) => a.localeCompare(b)),
+    rejectedToolNames: Array.from(rejectedToolNames).sort((a, b) => a.localeCompare(b)),
+    rejectionReasons: Array.from(rejectionReasons).sort((a, b) => a.localeCompare(b)),
+  };
+}
+
+function mergeToolActivityAudits(...audits) {
+  const valid = audits.filter((audit) => audit && typeof audit === "object");
+  const toolNames = new Set();
+  const rejectedToolNames = new Set();
+  const rejectionReasons = new Set();
+  const sources = [];
+  let totalToolCalls = 0;
+  let writeToolCalls = 0;
+  let rejectedToolCalls = 0;
+  let rejectedWriteToolCalls = 0;
+  for (const audit of valid) {
+    totalToolCalls = Math.max(totalToolCalls, Number(audit?.totalToolCalls || 0));
+    writeToolCalls = Math.max(writeToolCalls, Number(audit?.writeToolCalls || 0));
+    rejectedToolCalls = Math.max(rejectedToolCalls, Number(audit?.rejectedToolCalls || 0));
+    rejectedWriteToolCalls = Math.max(
+      rejectedWriteToolCalls,
+      Number(audit?.rejectedWriteToolCalls || 0)
+    );
+    if (
+      audit?.source &&
+      (audit.totalToolCalls ||
+        audit.writeToolCalls ||
+        audit.rejectedToolCalls ||
+        audit.rejectedWriteToolCalls)
+    ) {
+      sources.push(String(audit.source));
+    }
+    for (const tool of Array.isArray(audit?.toolNames) ? audit.toolNames : []) {
+      const normalized = normalizeToolName(tool);
+      if (normalized) toolNames.add(normalized);
+    }
+    for (const tool of Array.isArray(audit?.rejectedToolNames) ? audit.rejectedToolNames : []) {
+      const normalized = normalizeToolName(tool);
+      if (normalized) rejectedToolNames.add(normalized);
+    }
+    for (const reason of Array.isArray(audit?.rejectionReasons) ? audit.rejectionReasons : []) {
+      const normalized = String(reason || "").trim();
+      if (normalized) rejectionReasons.add(normalized);
+    }
+  }
+  return {
+    totalToolCalls,
+    writeToolCalls,
+    rejectedToolCalls,
+    rejectedWriteToolCalls,
+    toolNames: Array.from(toolNames).sort((a, b) => a.localeCompare(b)),
+    rejectedToolNames: Array.from(rejectedToolNames).sort((a, b) => a.localeCompare(b)),
+    rejectionReasons: Array.from(rejectionReasons).sort((a, b) => a.localeCompare(b)),
+    sources: Array.from(new Set(sources)),
+  };
+}
+
+function selectProviderWriteFailureReason(reasons) {
+  const list = Array.isArray(reasons) ? reasons : [];
+  if (list.includes("WRITE_ARGS_EMPTY_FROM_PROVIDER")) return "WRITE_ARGS_EMPTY_FROM_PROVIDER";
+  if (list.includes("WRITE_ARGS_UNPARSEABLE_FROM_PROVIDER")) {
+    return "WRITE_ARGS_UNPARSEABLE_FROM_PROVIDER";
+  }
+  return "";
+}
+
+function summarizeExecutionRows(rows, limit = 12) {
+  const list = Array.isArray(rows) ? rows : [];
+  const out = [];
+  for (const row of list) {
+    if (out.length >= limit) break;
+    const role = roleOfMessage(row);
+    const type = String(row?.type || "").trim().toLowerCase();
+    const text = textOfMessage(row).trim();
+    const parts = Array.isArray(row?.parts) ? row.parts : [];
+    const tools = [];
+    for (const part of parts) {
+      const tool = String(part?.tool || part?.name || "").trim();
+      if (tool) tools.push(normalizeToolName(tool) || tool);
+    }
+    const rowTool = String(row?.tool || row?.name || "").trim();
+    if (rowTool) tools.push(normalizeToolName(rowTool) || rowTool);
+    out.push({
+      role,
+      type: type || null,
+      tools: Array.from(new Set(tools)).slice(0, 8),
+      error: String(row?.error || "").trim() || null,
+      excerpt: text.slice(0, 240),
+    });
+  }
+  return out;
+}
+
+function buildAttemptTelemetry(name, request, rows, messages, startedAtMs, error = null, meta = {}) {
+  const syncAudit = collectToolActivity(rows, `${name}_prompt_sync`);
+  const sessionAudit = collectToolActivity(messages, `${name}_session_snapshot`);
+  const merged = mergeToolActivityAudits(syncAudit, sessionAudit);
+  const assistantText = extractAssistantText(rows) || extractAssistantText(messages);
+  return {
+    name,
+    attempt_index: Number(meta?.attemptIndex || 0),
+    strict_write_failure_class: String(meta?.failureClass || "").trim() || null,
+    strict_write_retry_remaining: Number(meta?.retryRemaining || 0),
+    started_at_ms: Number(startedAtMs || Date.now()),
+    tool_mode: String(request?.tool_mode || "").trim() || null,
+    tool_allowlist: Array.isArray(request?.tool_allowlist) ? request.tool_allowlist.slice() : [],
+    prompt_excerpt: String(request?.parts?.[0]?.text || "")
+      .trim()
+      .slice(0, 600),
+    assistant_present: !!assistantText.trim(),
+    assistant_excerpt: assistantText.trim().slice(0, 400),
+    any_tool_attempts: merged.totalToolCalls > 0 || merged.rejectedToolCalls > 0,
+    total_tool_calls: merged.totalToolCalls,
+    write_tool_calls: merged.writeToolCalls,
+    rejected_tool_calls: merged.rejectedToolCalls,
+    rejected_write_tool_calls: merged.rejectedWriteToolCalls,
+    tool_names: merged.toolNames,
+    rejected_tool_names: merged.rejectedToolNames,
+    rejection_reasons: merged.rejectionReasons,
+    detection_sources: merged.sources,
+    sync_row_count: Array.isArray(rows) ? rows.length : 0,
+    session_message_count: Array.isArray(messages) ? messages.length : 0,
+    sync_rows: summarizeExecutionRows(rows),
+    session_rows: summarizeExecutionRows(messages),
+    error: error ? String(error?.message || error || "").trim() : "",
+  };
+}
+
+function buildVerificationSummary(syncRows, messages, workspaceChanges, sessionId, options = {}) {
+  const syncAudit = collectToolActivity(syncRows, "prompt_sync");
+  const sessionAudit = collectToolActivity(messages, "session_snapshot");
+  const toolAudit = mergeToolActivityAudits(syncAudit, sessionAudit);
+  const assistantText = extractAssistantText(syncRows) || extractAssistantText(messages);
+  const mode = normalizeVerificationMode(options.verificationMode || swarmState.verificationMode);
+  const requiredToolModeUnsatisfied = assistantText.includes(REQUIRED_TOOL_MODE_REASON);
+  const requiredToolFailureReason = extractRequiredToolFailureReason(assistantText);
+  const providerWriteFailureReason = selectProviderWriteFailureReason(toolAudit.rejectionReasons);
+  const workspaceChanged = workspaceChanges?.hasChanges === true;
+  const strictMode = mode === "strict";
+  const passed = strictMode
+    ? workspaceChanged || toolAudit.writeToolCalls > 0
+    : workspaceChanged || toolAudit.totalToolCalls > 0;
+  let reason = "VERIFIED";
+  if (!passed) {
+    if (providerWriteFailureReason) reason = providerWriteFailureReason;
+    else if (requiredToolFailureReason) reason = requiredToolFailureReason;
+    else if (requiredToolModeUnsatisfied) reason = REQUIRED_TOOL_MODE_REASON;
+    else if (toolAudit.rejectedWriteToolCalls > 0)
+      reason = "WRITE_TOOL_ATTEMPT_REJECTED_NO_WORKSPACE_CHANGE";
+    else if (toolAudit.rejectedToolCalls > 0)
+      reason = "TOOL_ATTEMPT_REJECTED_NO_WORKSPACE_CHANGE";
+    else if (strictMode && toolAudit.totalToolCalls > 0)
+      reason = "NO_WRITE_ACTIVITY_NO_WORKSPACE_CHANGE";
+    else reason = "NO_TOOL_ACTIVITY_NO_WORKSPACE_CHANGE";
+  }
+  return {
+    mode,
+    reason,
+    passed,
+    session_id: String(sessionId || "").trim() || null,
+    assistant_present: !!assistantText.trim(),
+    assistant_excerpt: assistantText.trim().slice(0, 280),
+    any_tool_attempts: toolAudit.totalToolCalls > 0 || toolAudit.rejectedToolCalls > 0,
+    any_tool_calls: toolAudit.totalToolCalls > 0,
+    total_tool_calls: toolAudit.totalToolCalls,
+    write_tool_calls: toolAudit.writeToolCalls,
+    tool_names: toolAudit.toolNames,
+    rejected_tool_calls: toolAudit.rejectedToolCalls,
+    rejected_write_tool_calls: toolAudit.rejectedWriteToolCalls,
+    rejected_tool_names: toolAudit.rejectedToolNames,
+    rejection_reasons: toolAudit.rejectionReasons,
+    detection_sources: toolAudit.sources,
+    workspace_changed: workspaceChanged,
+    workspace_change_mode: String(workspaceChanges?.mode || "unknown"),
+    workspace_change_paths: Array.isArray(workspaceChanges?.paths)
+      ? workspaceChanges.paths.slice(0, 80)
+      : [],
+    workspace_change_summary: String(workspaceChanges?.summary || "").trim(),
+    execution_trace:
+      options?.executionTrace && typeof options.executionTrace === "object"
+        ? options.executionTrace
+        : undefined,
+  };
+}
+
+function hasToolActivity(rows) {
+  if (!Array.isArray(rows)) return false;
+  return rows.some((row) => {
+    const rowType = String(row?.type || "")
+      .trim()
+      .toLowerCase();
+    if (rowType.includes("tool")) return true;
+    const rowTool = String(row?.tool || "")
+      .trim()
+      .toLowerCase();
+    if (rowTool) return true;
+    const parts = Array.isArray(row?.parts) ? row.parts : [];
+    return parts.some((part) => {
+      const partType = String(part?.type || part?.part_type || "")
+        .trim()
+        .toLowerCase();
+      if (partType.includes("tool")) return true;
+      return String(part?.tool || "").trim().length > 0;
+    });
+  });
+}
+
+let cachedEngineDefaultModel = {
+  provider: "",
+  model: "",
+  fetchedAtMs: 0,
+};
+
+async function fetchEngineDefaultModel(session) {
+  const now = Date.now();
+  if (cachedEngineDefaultModel.fetchedAtMs && now - cachedEngineDefaultModel.fetchedAtMs < 15000) {
+    return { provider: cachedEngineDefaultModel.provider, model: cachedEngineDefaultModel.model };
+  }
+  const payload = await engineRequestJson(session, "/config/providers").catch(() => ({}));
+  const defaultProvider = String(payload?.default || "").trim();
+  const providers =
+    payload?.providers && typeof payload.providers === "object" ? payload.providers : {};
+  const defaultModel = String(providers?.[defaultProvider]?.default_model || "").trim();
+  cachedEngineDefaultModel = {
+    provider: defaultProvider,
+    model: defaultModel,
+    fetchedAtMs: now,
+  };
+  return { provider: defaultProvider, model: defaultModel };
+}
+
+async function resolveExecutionModel(session, run) {
+  const runProvider = String(run?.model_provider || "").trim();
+  const runModel = String(run?.model_id || "").trim();
+  if (runProvider && runModel) {
+    return { provider: runProvider, model: runModel, source: "run" };
+  }
+
+  const controller = getSwarmRunController(String(run?.run_id || "").trim());
+  const swarmProvider = String(controller?.modelProvider || swarmState.modelProvider || "").trim();
+  const swarmModel = String(controller?.modelId || swarmState.modelId || "").trim();
+  if (swarmProvider && swarmModel) {
+    return { provider: swarmProvider, model: swarmModel, source: "swarm_state" };
+  }
+
+  const defaults = await fetchEngineDefaultModel(session);
+  if (defaults.provider && defaults.model) {
+    return { provider: defaults.provider, model: defaults.model, source: "engine_default" };
+  }
+
+  throw new Error("MODEL_SELECTION_REQUIRED: no provider/model configured for swarm execution.");
+}
+
+function normalizeSessionModelRef(value) {
+  if (typeof value === "string") return value.trim();
+  if (value && typeof value === "object") {
+    const model =
+      String(
+        value?.model_id || value?.id || value?.name || value?.slug || value?.model || ""
+      ).trim();
+    if (model) return model;
+  }
+  return "";
+}
+
+function summarizeRunStepsForPrompt(run, currentStepId, limit = 12) {
+  const steps = Array.isArray(run?.steps) ? run.steps : [];
+  return steps
+    .slice(0, Math.max(1, Number(limit) || 12))
+    .map((row, index) => {
+      const stepId = String(row?.step_id || `step-${index + 1}`).trim();
+      const title = String(row?.title || stepId).trim();
+      const status = String(row?.status || "unknown").trim().toLowerCase();
+      const marker = stepId === currentStepId ? "*" : "-";
+      return `${marker} ${stepId} [${status}]: ${title}`;
+    })
+    .join("\n")
+    .trim();
+}
+
+function stepPromptText(run, step, stepIndex, totalSteps) {
+  const stepId = String(step?.step_id || "").trim() || `step-${stepIndex + 1}`;
+  const stepTitle = String(step?.title || stepId).trim();
+  const stepDetails =
+    step && typeof step === "object" ? JSON.stringify(step, null, 2).trim() : "";
+  const stepList = summarizeRunStepsForPrompt(run, stepId);
+  return [
+    "Execute this swarm step.",
+    "",
+    `Step (${stepIndex + 1}/${totalSteps}): ${stepTitle}`,
+    `Step ID: ${stepId}`,
+    `Workspace: ${String(run?.workspace?.canonical_path || "").trim()}`,
+    "",
+    "This step is already planned and assigned.",
+    "Treat the current assigned step as the authority for what to implement.",
+    "Use the original objective and step list only to clarify the assigned step, not to re-plan the run.",
+    "Do not create a new plan, do not restate the task graph, and do not describe future work.",
+    "Use workspace tools to implement this step now.",
+    "",
+    "Current assigned step payload:",
+    stepDetails || "{}",
+    "",
+    "Run step list:",
+    stepList || "(no step list available)",
+    "",
+    `Original objective: ${String(run?.objective || "").trim()}`,
+    "",
+    "Requirements:",
+    "- First inspect the relevant workspace files with read/glob/list/search if needed.",
+    "- Use list/ls/glob for directories. Use read only for concrete file paths.",
+    "- Make the required code/project changes for this step right now.",
+    "- Create or edit files as needed for this step only.",
+    "- If no relevant file exists yet, create the correct new file directly.",
+    "- A write call must include both a path and the full content to write.",
+    "- Use write/edit/apply_patch instead of a prose-only response.",
+    "- Keep scope limited to this step.",
+    "- Return a concise summary of the concrete file changes and blockers.",
+  ].join("\n");
+}
+
+function rowsSinceAttemptStart(rows, startIndex = 0) {
+  const list = Array.isArray(rows) ? rows : [];
+  const offset = Math.max(0, Number(startIndex) || 0);
+  if (!offset) return list;
+  return list.length > offset ? list.slice(offset) : list;
+}
+
+function parseDecisionPayload(text) {
+  const candidate = String(text || "").trim();
+  if (!candidate) return null;
+  const fencedJson = candidate.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const raw = (fencedJson?.[1] || candidate).trim();
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && parsed.decision ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function buildNonWritingVerificationSummary(syncRows, messages, sessionId, options = {}) {
+  const syncAudit = collectToolActivity(syncRows, "prompt_sync");
+  const sessionAudit = collectToolActivity(messages, "session_snapshot");
+  const toolAudit = mergeToolActivityAudits(syncAudit, sessionAudit);
+  const assistantText = extractAssistantText(syncRows) || extractAssistantText(messages);
+  const decisionPayload = parseDecisionPayload(assistantText);
+  const passed = toolAudit.totalToolCalls > 0 && !!decisionPayload;
+  const hasToolCalls = toolAudit.totalToolCalls > 0;
+  const hasDecisionPayload = !!decisionPayload;
+  let reason = "VERIFIED";
+  if (!passed) {
+    if (!hasToolCalls && !hasDecisionPayload) reason = "NO_TOOL_ACTIVITY_NO_DECISION";
+    else if (!hasToolCalls) reason = "NO_TOOL_ACTIVITY";
+    else reason = "DECISION_PAYLOAD_MISSING";
+  }
+  return {
+    mode: normalizeVerificationMode(options.verificationMode || swarmState.verificationMode),
+    reason,
+    passed,
+    session_id: String(sessionId || "").trim() || null,
+    assistant_present: !!assistantText.trim(),
+    assistant_excerpt: assistantText.trim().slice(0, 280),
+    any_tool_attempts: toolAudit.totalToolCalls > 0 || toolAudit.rejectedToolCalls > 0,
+    any_tool_calls: toolAudit.totalToolCalls > 0,
+    total_tool_calls: toolAudit.totalToolCalls,
+    write_tool_calls: toolAudit.writeToolCalls,
+    tool_names: toolAudit.toolNames,
+    rejected_tool_calls: toolAudit.rejectedToolCalls,
+    rejected_write_tool_calls: toolAudit.rejectedWriteToolCalls,
+    rejected_tool_names: toolAudit.rejectedToolNames,
+    rejection_reasons: toolAudit.rejectionReasons,
+    detection_sources: toolAudit.sources,
+    workspace_changed: false,
+    workspace_change_mode: "not_required",
+    workspace_change_paths: [],
+    workspace_change_summary: "Workspace changes not required for this task kind.",
+    decision_payload: decisionPayload,
+    execution_trace:
+      options?.executionTrace && typeof options.executionTrace === "object"
+        ? options.executionTrace
+        : undefined,
+  };
+}
+
+async function runExecutionPromptWithVerification(session, run, prompt, sessionId = "", options = {}) {
+  const activeSessionId =
+    String(sessionId || "").trim() || (await createExecutionSession(session, run));
+  if (!activeSessionId) throw new Error("Failed to create execution session.");
+  const runId = String(run?.run_id || "").trim();
+  const controller = getSwarmRunController(runId);
+  const workspaceRoot = await workspaceExistsAsDirectory(
+    String(
+      run?.workspace?.canonical_path ||
+        run?.workspace_root ||
+        controller?.workspaceRoot ||
+        swarmState.workspaceRoot ||
+        REPO_ROOT
+    ).trim()
+  );
+  let workspaceBefore = null;
+  let workspaceAfter = null;
+  let workspaceChanges = {
+    mode: "unavailable",
+    hasChanges: false,
+    paths: [],
+    summary: "",
+  };
+  const resolvedModel = await resolveExecutionModel(session, run);
+  const writeRequired = options.writeRequired !== false;
+  const maxAttempts = writeRequired
+    ? strictWriteRetryEnabled()
+      ? strictWriteRetryMaxAttempts()
+      : 1
+    : nonWritingRetryMaxAttempts();
+  const attempts = [];
+  const workspaceSeedPaths = () => [
+    ...Object.keys(workspaceBefore?.files || {}),
+    ...Object.keys(workspaceBefore?.statusByPath || {}),
+  ];
+  if (workspaceRoot) {
+    workspaceBefore = await captureWorkspaceSnapshot(workspaceRoot).catch((error) => ({
+      mode: "capture_failed",
+      root: workspaceRoot,
+      files: {},
+      statusByPath: {},
+      error: String(error?.message || error || "workspace snapshot failed"),
+    }));
+  }
+  let previousSyncCount = 0;
+  let previousMessageCount = 0;
+  let syncRows = [];
+  let messages = [];
+  let verification = null;
+  let attemptError = null;
+  let hasAssistant = false;
+  let persistedAssistant = false;
+  let lastSessionSnapshot = null;
+  for (let attemptIndex = 1; attemptIndex <= maxAttempts; attemptIndex += 1) {
+    attemptError = null;
+    const requestBody =
+      attemptIndex === 1
+        ? {
+            parts: [{ type: "text", text: prompt }],
+            tool_mode: "required",
+            tool_allowlist:
+              options.toolAllowlist ||
+              (writeRequired
+                ? workerExecutionToolAllowlist()
+                : ["ls", "list", "glob", "search", "grep", "codesearch", "read"]),
+            write_required: writeRequired ? true : undefined,
+          }
+        : writeRequired
+          ? buildStrictWriteRetryRequest(prompt, verification, attemptIndex, maxAttempts)
+          : buildNonWritingRetryRequest(prompt, verification, attemptIndex, maxAttempts);
+    const promptResponse = await engineRequestJson(
+      session,
+      `/session/${encodeURIComponent(activeSessionId)}/prompt_sync`,
+      {
+        method: "POST",
+        timeoutMs: 10 * 60 * 1000,
+        body: requestBody,
+      }
+    ).catch((error) => {
+      attemptError = error;
+      return null;
+    });
+    const allSyncRows = Array.isArray(promptResponse) ? promptResponse : [];
+    syncRows = rowsSinceAttemptStart(allSyncRows, previousSyncCount);
+    previousSyncCount = allSyncRows.length;
+    const sessionSnapshot = await engineRequestJson(
+      session,
+      `/session/${encodeURIComponent(activeSessionId)}`
+    ).catch(() => null);
+    lastSessionSnapshot = sessionSnapshot;
+    const sessionMessages = Array.isArray(sessionSnapshot?.messages) ? sessionSnapshot.messages : [];
+    messages = rowsSinceAttemptStart(sessionMessages, previousMessageCount);
+    previousMessageCount = sessionMessages.length;
+    hasAssistant = syncRows.some((row) => roleOfMessage(row) === "assistant");
+    persistedAssistant = messages.some((message) => roleOfMessage(message) === "assistant");
+
+    if (workspaceRoot) {
+      workspaceAfter = await captureWorkspaceSnapshot(workspaceRoot, {
+        includePaths: workspaceSeedPaths(),
+      }).catch((error) => ({
+        mode: "capture_failed",
+        root: workspaceRoot,
+        files: {},
+        statusByPath: {},
+        error: String(error?.message || error || "workspace snapshot failed"),
+      }));
+    }
+    if (workspaceBefore && workspaceAfter) {
+      workspaceChanges = summarizeWorkspaceChanges(workspaceBefore, workspaceAfter);
+      if (workspaceBefore?.error || workspaceAfter?.error) {
+        const detail = [workspaceBefore?.error, workspaceAfter?.error].filter(Boolean).join(" | ");
+        workspaceChanges.summary = [
+          workspaceChanges.summary,
+          detail ? `Workspace snapshot warnings: ${detail}` : "",
+        ]
+          .filter(Boolean)
+          .join("\n");
+      }
+    }
+    verification = writeRequired
+      ? buildVerificationSummary(syncRows, messages, workspaceChanges, activeSessionId, {
+          verificationMode: controller?.verificationMode || swarmState.verificationMode,
+        })
+      : buildNonWritingVerificationSummary(syncRows, messages, activeSessionId, {
+          verificationMode: controller?.verificationMode || swarmState.verificationMode,
+        });
+    const failureClass = writeRequired
+      ? classifyStrictWriteFailureReason(verification)
+      : classifyNonWritingFailureReason(verification);
+    attempts.push(
+      buildAttemptTelemetry(
+        attemptIndex === 1 ? "initial" : `retry_${attemptIndex - 1}`,
+        requestBody,
+        syncRows,
+        messages,
+        Date.now(),
+        attemptError,
+        {
+          attemptIndex,
+          failureClass,
+          retryRemaining: maxAttempts - attemptIndex,
+        }
+      )
+    );
+    if (verification?.passed) break;
+    if (!failureClass || attemptIndex >= maxAttempts) break;
+  }
+  const executionTrace = {
+    session_id: activeSessionId,
+    model: {
+      provider: String(lastSessionSnapshot?.provider || resolvedModel?.provider || "").trim(),
+      model_id:
+        normalizeSessionModelRef(lastSessionSnapshot?.model) ||
+        normalizeSessionModelRef(resolvedModel?.model),
+      source: String(
+        lastSessionSnapshot?.provider &&
+          normalizeSessionModelRef(lastSessionSnapshot?.model)
+          ? "session_snapshot"
+          : resolvedModel?.source || ""
+      ).trim(),
+    },
+    attempts,
+  };
+  verification = writeRequired
+    ? buildVerificationSummary(syncRows, messages, workspaceChanges, activeSessionId, {
+        verificationMode: controller?.verificationMode || swarmState.verificationMode,
+        executionTrace,
+      })
+    : buildNonWritingVerificationSummary(syncRows, messages, activeSessionId, {
+        verificationMode: controller?.verificationMode || swarmState.verificationMode,
+        executionTrace,
+      });
+  if (attemptError && !hasAssistant && !persistedAssistant) {
+    throw createExecutionError(`PROMPT_RETRY_FAILED: ${attemptError.message}`, {
+      sessionId: activeSessionId,
+      verification: {
+        ...verification,
+        reason: "PROMPT_RETRY_FAILED",
+        passed: false,
+        assistant_present: false,
+        retry_error: String(attemptError?.message || attemptError || "").trim(),
+      },
+    });
+  }
+  if (!hasAssistant && !persistedAssistant) {
+    throw createExecutionError(
+      "PROMPT_DISPATCH_EMPTY_RESPONSE: prompt_sync returned no assistant output. Model route may be unresolved.",
+      {
+        sessionId: activeSessionId,
+        verification: {
+          ...verification,
+          reason: "PROMPT_DISPATCH_EMPTY_RESPONSE",
+          passed: false,
+          assistant_present: false,
+        },
+      }
+    );
+  }
+  if (!verification.passed) {
+    throw createExecutionError(`TASK_NOT_VERIFIED: ${verification.reason}`, {
+      sessionId: activeSessionId,
+      verification,
+    });
+  }
+  return { sessionId: activeSessionId, verification };
+}
+
+async function runStepWithLLM(session, run, step, stepIndex, totalSteps, sessionId = "") {
+  const prompt = stepPromptText(run, step, stepIndex, totalSteps);
+  return runExecutionPromptWithVerification(session, run, prompt, sessionId);
+}
+
+function extractBlackboardTasks(blackboardPayload) {
+  const board =
+    blackboardPayload?.blackboard && typeof blackboardPayload.blackboard === "object"
+      ? blackboardPayload.blackboard
+      : {};
+  return Array.isArray(board?.tasks) ? board.tasks : [];
+}
+
+function isTerminalTaskStatus(status) {
+  const normalized = String(status || "")
+    .trim()
+    .toLowerCase();
+  return ["done", "completed", "failed", "cancelled", "canceled"].includes(normalized);
+}
+
+function isCompletedTaskStatus(status) {
+  const normalized = String(status || "")
+    .trim()
+    .toLowerCase();
+  return ["done", "completed"].includes(normalized);
+}
+
+function extractClaimedTask(payload) {
+  if (payload?.task && typeof payload.task === "object") return payload.task;
+  if (Array.isArray(payload?.tasks) && payload.tasks[0] && typeof payload.tasks[0] === "object") {
+    return payload.tasks[0];
+  }
+  if (payload && typeof payload === "object" && String(payload.id || "").trim()) {
+    return payload;
+  }
+  return null;
+}
+
+function taskTitleFromRecord(task) {
+  const payload = task?.payload && typeof task.payload === "object" ? task.payload : {};
+  return String(payload?.title || task?.title || task?.task_type || task?.id || "task").trim();
+}
+
+function taskKindFromRecord(task) {
+  const payload = task?.payload && typeof task.payload === "object" ? task.payload : {};
+  const raw = String(payload?.task_kind || task?.task_type || "inspection").trim().toLowerCase();
+  return ["implementation", "inspection", "research", "validation"].includes(raw)
+    ? raw
+    : "inspection";
+}
+
+function isNonWritingTaskRecord(task) {
+  return taskKindFromRecord(task) !== "implementation";
+}
+
+function summarizeBlackboardTasksForPrompt(tasks, currentTaskId, limit = 16) {
+  const list = Array.isArray(tasks) ? tasks : [];
+  return list
+    .slice(0, Math.max(1, Number(limit) || 16))
+    .map((task, index) => {
+      const taskId = String(task?.id || `task-${index + 1}`).trim();
+      const title = taskTitleFromRecord(task);
+      const status = String(task?.status || "unknown").trim().toLowerCase();
+      const marker = taskId === currentTaskId ? "*" : "-";
+      return `${marker} ${taskId} [${status}]: ${title}`;
+    })
+    .join("\n")
+    .trim();
+}
+
+function taskPromptText(run, task, workerId, workflowId) {
+  const taskId = String(task?.id || "").trim();
+  const taskTitle = taskTitleFromRecord(task);
+  const taskKind = taskKindFromRecord(task);
+  const taskDetails =
+    task && typeof task === "object" ? JSON.stringify(task, null, 2).trim() : "";
+  const taskList = summarizeBlackboardTasksForPrompt(run?.tasks, taskId);
+  const outputTarget =
+    task?.payload?.output_target && typeof task.payload.output_target === "object"
+      ? task.payload.output_target
+      : task?.output_target && typeof task.output_target === "object"
+        ? task.output_target
+        : null;
+  const outputPath = String(outputTarget?.path || "").trim();
+  const outputKind = String(outputTarget?.kind || "artifact").trim();
+  const outputOperation = String(outputTarget?.operation || "create_or_update").trim();
+  if (taskKind !== "implementation") {
+    return [
+      "Execute this swarm blackboard task.",
+      "",
+      `Task: ${taskTitle}`,
+      `Task ID: ${taskId}`,
+      `Task Kind: ${taskKind}`,
+      `Workflow: ${String(workflowId || task?.workflow_id || "swarm.blackboard.default").trim()}`,
+      `Agent: ${workerId}`,
+      `Workspace: ${String(run?.workspace?.canonical_path || "").trim()}`,
+      "",
+      "This is a non-writing research/inspection task.",
+      "Treat the current assigned task as the authority for what to inspect or decide.",
+      "Use the original objective and task list only to clarify the assigned task, not to re-plan the run.",
+      "Do not create a new plan, do not restate the task graph, and do not describe future work.",
+      "Use read-only tools to inspect the workspace now.",
+      "",
+      "Current assigned task payload:",
+      taskDetails || "{}",
+      "",
+      "Run blackboard task list:",
+      taskList || "(no task list available)",
+      "",
+      `Original objective: ${String(run?.objective || "").trim()}`,
+      "",
+      "Requirements:",
+      "- You must use tools in this task.",
+      "- Use only read-only tools such as ls/list/glob/search/grep/codesearch/read.",
+      "- Do not call write/edit/apply_patch for this task.",
+      "- Return a concise structured JSON decision object with your findings.",
+      "- If you decide a future artifact path, include `output_target.path` in the JSON.",
+      '- Output shape: {"decision":{"summary":"...","output_target":{"path":"...","kind":"artifact","operation":"create_or_update"},"evidence":["..."]}}',
+    ].join("\n");
+  }
+  return [
+    "Execute this swarm blackboard task.",
+    "",
+    `Task: ${taskTitle}`,
+    `Task ID: ${taskId}`,
+    `Task Kind: ${taskKind}`,
+    `Workflow: ${String(workflowId || task?.workflow_id || "swarm.blackboard.default").trim()}`,
+    `Agent: ${workerId}`,
+    `Workspace: ${String(run?.workspace?.canonical_path || "").trim()}`,
+    "",
+    "This task is already planned and assigned.",
+    "Treat the current assigned task as the authority for what to implement.",
+    "Use the original objective and task list only to clarify the assigned task, not to re-plan the run.",
+    "Do not create a new plan, do not restate the task graph, and do not describe future work.",
+    "Use workspace tools to implement this task now.",
+    "",
+    "Current assigned task payload:",
+    taskDetails || "{}",
+    "",
+    "Required output target:",
+    outputPath
+      ? JSON.stringify(
+          {
+            path: outputPath,
+            kind: outputKind,
+            operation: outputOperation,
+          },
+          null,
+          2
+        )
+      : '{"path":"","kind":"artifact","operation":"create_or_update"}',
+    "",
+    "Run blackboard task list:",
+    taskList || "(no task list available)",
+    "",
+    `Original objective: ${String(run?.objective || "").trim()}`,
+    "",
+    "Requirements:",
+    "- First inspect the relevant workspace files with read/glob/list/search if needed.",
+    "- If the target file does not exist, create the COMPLETE file in a single write call.",
+    "- Do not split the implementation across multiple tool calls if the result should be one file.",
+    "- Use list/ls/glob for directories. Use read only for concrete file paths.",
+    "- Implement this task in the workspace right now.",
+    "- Create or edit files as needed for this task only.",
+    outputPath
+      ? `- The required output for this task is \`${outputPath}\` (${outputKind}, ${outputOperation}).`
+      : "- The required output target is missing; do not guess a file path.",
+    "- If the target file does not exist yet, create it directly.",
+    "- A write call must include both a path and the full content to write.",
+    "- Use write/edit/apply_patch instead of a prose-only response.",
+    "- Keep scope limited to this task.",
+    "- Return a concise summary of the concrete file changes and blockers.",
+  ].join("\n");
+}
+
+async function runTaskWithLLM(session, run, task, workerId, workflowId, sessionId = "") {
+  const prompt = taskPromptText(run, task, workerId, workflowId);
+  return runExecutionPromptWithVerification(session, run, prompt, sessionId, {
+    writeRequired: !isNonWritingTaskRecord(task),
+  });
+}
+
+async function fetchBlackboardTasks(session, runId) {
+  const payload = await engineRequestJson(
+    session,
+    `/context/runs/${encodeURIComponent(runId)}/blackboard`
+  ).catch(() => ({}));
+  return extractBlackboardTasks(payload);
+}
+
+async function seedBlackboardTasks(session, runId, objective, taskRows, workflowId) {
+  const normalizedTasks = ensurePlannerTaskOutputTargets(
+    normalizePlannerTasks(taskRows, 128, { linearFallback: true }),
+    objective
+  );
+  const validTaskIds = new Set(normalizedTasks.map((task) => task.id));
+  const prepared = normalizedTasks
+    .map((task, idx, list) => ({
+      id: String(task?.id || `task-${idx + 1}`).trim(),
+      task_type: String(task?.taskKind || "inspection").trim(),
+      workflow_id: workflowId,
+      depends_on_task_ids: (Array.isArray(task?.dependsOnTaskIds) ? task.dependsOnTaskIds : [])
+        .map((dep) => String(dep || "").trim())
+        .filter((dep) => dep && validTaskIds.has(dep)),
+      payload: {
+        title: String(task?.title || "").trim(),
+        task_kind: String(task?.taskKind || "inspection").trim(),
+        objective,
+        step_index: idx + 1,
+        total_steps: list.length,
+        output_target: task?.outputTarget || null,
+      },
+    }))
+    .filter((task) => String(task?.payload?.title || "").trim().length >= 6);
+  if (!prepared.length) {
+    throw new Error("No valid tasks to seed.");
+  }
+  const created = await engineRequestJson(session, `/context/runs/${encodeURIComponent(runId)}/tasks`, {
+    method: "POST",
+    body: { tasks: prepared },
+  });
+  if (created && created.ok === false) {
+    throw new Error(String(created.error || created.code || "Task seeding failed."));
+  }
+  const seeded = await fetchBlackboardTasks(session, runId);
+  if (!seeded.length) {
+    throw new Error("Task seeding returned no blackboard tasks.");
+  }
+  return { mode: "blackboard", count: seeded.length };
+}
+
+async function transitionBlackboardTask(session, runId, task, update = {}) {
+  const taskId = String(task?.id || update.taskId || "").trim();
+  if (!taskId) throw new Error("Missing task id for transition.");
+  const expectedTaskRev = task?.task_rev ?? update.expectedTaskRev;
+  const leaseToken = task?.lease_token || task?.leaseToken || update.leaseToken;
+  const agentId = update.agentId || task?.assigned_agent || task?.lease_owner || undefined;
+  return engineRequestJson(
+    session,
+    `/context/runs/${encodeURIComponent(runId)}/tasks/${encodeURIComponent(taskId)}/transition`,
+    {
+      method: "POST",
+      body: {
+        action: String(update.action || "status").trim() || "status",
+        status: update.status || undefined,
+        error: update.error || undefined,
+        command_id: update.commandId || undefined,
+        expected_task_rev: expectedTaskRev ?? undefined,
+        lease_token: leaseToken || undefined,
+        agent_id: agentId || undefined,
+      },
+    }
+  );
+}
+
+async function detectExecutorMode(session, runId) {
+  const blackboardTasks = await fetchBlackboardTasks(session, runId);
+  if (blackboardTasks.length) return "blackboard";
+  const payload = await engineRequestJson(
+    session,
+    `/context/runs/${encodeURIComponent(runId)}`
+  ).catch(() => null);
+  const steps = Array.isArray(payload?.run?.steps) ? payload.run.steps : [];
+  if (steps.length) return "context_steps";
+  return String(
+    getSwarmRunController(runId)?.executorMode || swarmState.executorMode || "context_steps"
+  );
+}
+
+const swarmExecutors = new Map();
+
+function findStepByStatus(steps, status) {
+  return (Array.isArray(steps) ? steps : []).find(
+    (step) =>
+      String(step?.status || "")
+        .trim()
+        .toLowerCase() === status
+  );
+}
+
+async function ensureStepMarkedDone(session, runId, stepId) {
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const payload = await engineRequestJson(
+      session,
+      `/context/runs/${encodeURIComponent(runId)}`
+    ).catch(() => null);
+    const run = payload?.run;
+    const steps = Array.isArray(run?.steps) ? run.steps : [];
+    const idx = steps.findIndex((step) => String(step?.step_id || "") === stepId);
+    if (idx < 0) return true;
+    const current = String(steps[idx]?.status || "").toLowerCase();
+    if (current === "done") return true;
+    if (attempt < 2) {
+      await sleep(120);
+      continue;
+    }
+    const patched = {
+      ...run,
+      status: "running",
+      why_next_step: `reconciled completion for ${stepId}`,
+      steps: steps.map((step, i) => (i === idx ? { ...step, status: "done" } : step)),
+    };
+    await engineRequestJson(session, `/context/runs/${encodeURIComponent(runId)}`, {
+      method: "PUT",
+      body: patched,
+    });
+    const verify = await engineRequestJson(
+      session,
+      `/context/runs/${encodeURIComponent(runId)}`
+    ).catch(() => null);
+    const verifySteps = Array.isArray(verify?.run?.steps) ? verify.run.steps : [];
+    const verifyStep = verifySteps.find((step) => String(step?.step_id || "") === stepId);
+    return String(verifyStep?.status || "").toLowerCase() === "done";
+  }
+  return false;
+}
+
+async function driveContextRunExecution(session, runId) {
+  if (swarmExecutors.has(runId)) return false;
+  upsertSwarmRunController(runId, {
+    executorState: "running",
+    executorReason: "",
+  });
+  const runner = (async () => {
+    let completionStreak = 0;
+    let lastCompletedStepId = "";
+    for (let cycle = 0; cycle < 24; cycle += 1) {
+      const runPayload = await engineRequestJson(
+        session,
+        `/context/runs/${encodeURIComponent(runId)}`
+      );
+      const run = runPayload?.run || {};
+      if (isRunTerminal(run.status)) return;
+
+      const nextPayload = await engineRequestJson(
+        session,
+        `/context/runs/${encodeURIComponent(runId)}/driver/next`,
+        {
+          method: "POST",
+          body: { dry_run: false },
+        }
+      );
+      const selectedStepId = String(nextPayload?.selected_step_id || "").trim();
+      const latestRun = nextPayload?.run || run;
+      const steps = Array.isArray(latestRun?.steps) ? latestRun.steps : [];
+      const inProgressStep = findStepByStatus(steps, "in_progress");
+      const executionStepId = selectedStepId || String(inProgressStep?.step_id || "").trim();
+
+      if (!executionStepId) {
+        if (
+          steps.length &&
+          steps.every((step) => String(step?.status || "").toLowerCase() === "done")
+        ) {
+          await appendContextRunEvent(session, runId, "run_completed", "completed", {
+            why_next_step: "all steps completed",
+          });
+          upsertSwarmRunController(runId, {
+            lastError: "",
+            status: "completed",
+            stoppedAt: Date.now(),
+            executorState: "idle",
+            executorReason: "run completed",
+          });
+          return;
+        }
+        const blockedReason = String(
+          nextPayload?.why_next_step || latestRun?.why_next_step || "No actionable step selected."
+        );
+        upsertSwarmRunController(runId, {
+          lastError: blockedReason,
+          status: "blocked",
+          executorState: "blocked",
+          executorReason: blockedReason,
+        });
+        return;
+      }
+
+      const stepIndex = steps.findIndex((step) => String(step?.step_id || "") === executionStepId);
+      const step =
+        stepIndex >= 0 ? steps[stepIndex] : { step_id: executionStepId, title: executionStepId };
+      let stepSessionId = "";
+
+      try {
+        stepSessionId = await createExecutionSession(session, latestRun);
+        await appendContextRunEvent(
+          session,
+          runId,
+          "step_started",
+          "running",
+          {
+            step_status: "in_progress",
+            step_title: String(step?.title || executionStepId),
+            session_id: stepSessionId || null,
+            why_next_step: selectedStepId
+              ? `executing ${executionStepId}`
+              : `resuming in_progress step ${executionStepId}`,
+          },
+          executionStepId
+        );
+        const { sessionId, verification } = await runStepWithLLM(
+          session,
+          latestRun,
+          step,
+          Math.max(stepIndex, 0),
+          Math.max(steps.length, 1),
+          stepSessionId
+        );
+        await appendContextRunEvent(
+          session,
+          runId,
+          "step_completed",
+          "running",
+          {
+            step_status: "done",
+            step_title: String(step?.title || executionStepId),
+            session_id: sessionId,
+            verification,
+            why_next_step: `completed ${executionStepId}`,
+          },
+          executionStepId
+        );
+        const refresh = await engineRequestJson(
+          session,
+          `/context/runs/${encodeURIComponent(runId)}`
+        ).catch(() => null);
+        const refreshedSteps = Array.isArray(refresh?.run?.steps) ? refresh.run.steps : [];
+        const refreshedStep = refreshedSteps.find(
+          (item) => String(item?.step_id || "") === executionStepId
+        );
+        const refreshedStatus = String(refreshedStep?.status || "").toLowerCase();
+        if (refreshedStatus !== "done") {
+          const reconciled = await ensureStepMarkedDone(session, runId, executionStepId);
+          if (reconciled) {
+            await appendContextRunEvent(
+              session,
+              runId,
+              "step_completion_reconciled",
+              "running",
+              {
+                step_status: "done",
+                why_next_step: `reconciled stale step state for ${executionStepId}`,
+              },
+              executionStepId
+            );
+          } else {
+            throw new Error(
+              `STEP_STATE_NOT_ADVANCING: step \`${executionStepId}\` remained \`${refreshedStatus || "unknown"}\` after completion`
+            );
+          }
+        }
+        if (executionStepId === lastCompletedStepId) completionStreak += 1;
+        else {
+          lastCompletedStepId = executionStepId;
+          completionStreak = 1;
+        }
+        if (completionStreak > 2) {
+          throw new Error(`STEP_LOOP_GUARD: repeated completion on step \`${executionStepId}\``);
+        }
+        upsertSwarmRunController(runId, {
+          lastError: "",
+          status: "running",
+          executorState: "running",
+          executorReason: "",
+        });
+      } catch (error) {
+        const message = String(error?.message || error || "Unknown step failure");
+        const failureSessionId = String(error?.sessionId || stepSessionId || "").trim();
+        const verification =
+          error?.verification && typeof error.verification === "object"
+            ? error.verification
+            : undefined;
+        upsertSwarmRunController(runId, {
+          lastError: message,
+          status: "failed",
+          executorState: "error",
+          executorReason: message,
+        });
+        await appendContextRunEvent(
+          session,
+          runId,
+          "step_failed",
+          "failed",
+          {
+            step_status: "failed",
+            session_id: failureSessionId || null,
+            verification,
+            error: message,
+            why_next_step: `step failed: ${executionStepId}`,
+          },
+          executionStepId
+        );
+        return;
+      }
+    }
+  })()
+    .catch((error) => {
+      const message = String(error?.message || error || "Run executor failed");
+      upsertSwarmRunController(runId, {
+        lastError: message,
+        status: "failed",
+        executorState: "error",
+        executorReason: message,
+      });
+    })
+    .finally(() => {
+      swarmExecutors.delete(runId);
+      const controller = getSwarmRunController(runId);
+      if (String(controller?.executorState || "") === "running") {
+        upsertSwarmRunController(runId, {
+          executorState: "idle",
+          executorReason: "",
+        });
+      }
+    });
+  swarmExecutors.set(runId, runner);
+  return true;
+}
+
+async function driveBlackboardRunExecution(session, runId, options = {}) {
+  if (swarmExecutors.has(runId)) return false;
+  const controller = getSwarmRunController(runId);
+  const workflowId = String(
+    options.workflowId || controller?.workflowId || swarmState.workflowId || "swarm.blackboard.default"
+  ).trim();
+  const maxAgents = Math.max(
+    1,
+    Math.min(
+      16,
+      Number.parseInt(String(options.maxAgents || controller?.maxAgents || swarmState.maxAgents || 3), 10) || 3
+    )
+  );
+  upsertSwarmRunController(runId, {
+    executorState: "running",
+    executorReason: "",
+    executorMode: "blackboard",
+  });
+
+  const runner = (async () => {
+    let completionAnnounced = false;
+    const markRunComplete = async (reason) => {
+      if (completionAnnounced) return;
+      completionAnnounced = true;
+      await appendContextRunEvent(session, runId, "run_completed", "completed", {
+        why_next_step: String(reason || "all tasks completed"),
+      });
+      upsertSwarmRunController(runId, {
+        lastError: "",
+        status: "completed",
+        stoppedAt: Date.now(),
+        executorState: "idle",
+        executorReason: "run completed",
+      });
+    };
+
+    const workers = Array.from({ length: maxAgents }).map((_, index) => {
+      const agentId = `swarm-agent-${index + 1}`;
+      return (async () => {
+        let idleSpins = 0;
+        for (let cycle = 0; cycle < 96; cycle += 1) {
+          const runPayload = await engineRequestJson(
+            session,
+            `/context/runs/${encodeURIComponent(runId)}`
+          ).catch(() => null);
+          const run = runPayload?.run || {};
+          if (isRunTerminal(run.status)) return;
+
+          const boardTasks = await fetchBlackboardTasks(session, runId);
+          const openTasks = boardTasks.filter((task) => !isTerminalTaskStatus(task?.status));
+          if (!openTasks.length && boardTasks.length) {
+            await markRunComplete("all blackboard tasks completed");
+            return;
+          }
+
+          const claimedPayload = await engineRequestJson(
+            session,
+            `/context/runs/${encodeURIComponent(runId)}/tasks/claim`,
+            {
+              method: "POST",
+              body: {
+                agent_id: agentId,
+                workflow_id: workflowId || undefined,
+                lease_ms: 45000,
+              },
+            }
+          ).catch(() => null);
+          const task = extractClaimedTask(claimedPayload);
+          if (!task) {
+            idleSpins += 1;
+            if (idleSpins > 6) {
+              const refreshedBoard = await fetchBlackboardTasks(session, runId);
+              if (
+                refreshedBoard.length &&
+                refreshedBoard.every((row) => isCompletedTaskStatus(row?.status))
+              ) {
+                await markRunComplete("all blackboard tasks completed");
+                return;
+              }
+              idleSpins = 0;
+            }
+            await sleep(500);
+            continue;
+          }
+          idleSpins = 0;
+          const taskId = String(task?.id || "").trim();
+          const title = taskTitleFromRecord(task);
+          let taskSessionId = "";
+          try {
+            taskSessionId = await createExecutionSession(session, run);
+            await appendContextRunEvent(
+              session,
+              runId,
+              "task_started",
+              "running",
+              {
+                step_status: "in_progress",
+                step_title: title,
+                session_id: taskSessionId || null,
+                workflow_id: String(task?.workflow_id || workflowId || "").trim(),
+                assigned_agent: agentId,
+                why_next_step: `executing ${taskId || title}`,
+              },
+              taskId || null
+            );
+            const runSnapshot = await engineRequestJson(
+              session,
+              `/context/runs/${encodeURIComponent(runId)}`
+            ).catch(() => ({ run: {} }));
+            const { sessionId, verification } = await runTaskWithLLM(
+              session,
+              runSnapshot?.run || run,
+              task,
+              agentId,
+              workflowId,
+              taskSessionId
+            );
+            await transitionBlackboardTask(session, runId, task, {
+              status: "done",
+              agentId,
+              commandId: sessionId,
+            }).catch(() => null);
+            await appendContextRunEvent(
+              session,
+              runId,
+              "task_completed",
+              "running",
+              {
+                step_status: "done",
+                step_title: title,
+                session_id: sessionId,
+                verification,
+                workflow_id: String(task?.workflow_id || workflowId || "").trim(),
+                assigned_agent: agentId,
+                why_next_step: `completed ${taskId || title}`,
+              },
+              taskId || null
+            );
+            upsertSwarmRunController(runId, {
+              lastError: "",
+              status: "running",
+              executorState: "running",
+              executorReason: "",
+            });
+          } catch (error) {
+            const message = String(error?.message || error || "Unknown task failure");
+            const failureSessionId = String(error?.sessionId || taskSessionId || "").trim();
+            const verification =
+              error?.verification && typeof error.verification === "object"
+                ? error.verification
+                : undefined;
+            await transitionBlackboardTask(session, runId, task, {
+              status: "failed",
+              error: message,
+              agentId,
+            }).catch(() => null);
+            upsertSwarmRunController(runId, {
+              lastError: message,
+              status: "failed",
+              executorState: "error",
+              executorReason: message,
+            });
+            await appendContextRunEvent(
+              session,
+              runId,
+              "task_failed",
+              "failed",
+              {
+                step_status: "failed",
+                step_title: title,
+                session_id: failureSessionId || null,
+                verification,
+                workflow_id: String(task?.workflow_id || workflowId || "").trim(),
+                assigned_agent: agentId,
+                error: message,
+                why_next_step: `task failed: ${taskId || title}`,
+              },
+              taskId || null
+            );
+            return;
+          }
+        }
+      })();
+    });
+    await Promise.all(workers);
+  })()
+    .catch((error) => {
+      const message = String(error?.message || error || "Run executor failed");
+      upsertSwarmRunController(runId, {
+        lastError: message,
+        status: "failed",
+        executorState: "error",
+        executorReason: message,
+      });
+    })
+    .finally(() => {
+      swarmExecutors.delete(runId);
+      const current = getSwarmRunController(runId);
+      if (String(current?.executorState || "") === "running") {
+        upsertSwarmRunController(runId, {
+          executorState: "idle",
+          executorReason: "",
+        });
+      }
+    });
+  swarmExecutors.set(runId, runner);
+  return true;
+}
+
+async function startRunExecutor(session, runId, options = {}) {
+  const mode = String(options.mode || "").trim() || (await detectExecutorMode(session, runId));
+  upsertSwarmRunController(runId, { executorMode: mode });
+  if (mode === "blackboard") {
+    return driveBlackboardRunExecution(session, runId, options);
+  }
+  return driveContextRunExecution(session, runId);
+}
+
+async function requeueInProgressSteps(session, runId) {
+  const payload = await engineRequestJson(
+    session,
+    `/context/runs/${encodeURIComponent(runId)}`
+  ).catch(() => null);
+  const run = payload?.run;
+  const steps = Array.isArray(run?.steps) ? run.steps : [];
+  const inProgress = steps.filter(
+    (step) =>
+      String(step?.status || "")
+        .trim()
+        .toLowerCase() === "in_progress"
+  );
+  for (const step of inProgress) {
+    const stepId = String(step?.step_id || "").trim();
+    if (!stepId) continue;
+    await appendContextRunEvent(
+      session,
+      runId,
+      "task_retry_requested",
+      "running",
+      {
+        why_next_step: `requeued stale in_progress step \`${stepId}\` before continue`,
+      },
+      stepId
+    );
+  }
+  return inProgress.length;
+}
+
+async function startSwarm(session, config = {}) {
+  const objective = String(config.objective || "Ship a small feature end-to-end").trim();
+  const workspaceCandidates = [
+    config.workspaceRoot,
+    config.workspace_root,
+    config.workspace?.canonical_path,
+    config.workspace?.workspace_root,
+    config.repoRoot,
+    config.repo_root,
+  ];
+  const workspaceRootRaw = workspaceCandidates
+    .map((value) => String(value || "").trim())
+    .find((value) => value.length > 0);
+  if (!workspaceRootRaw) {
+    throw new Error(
+      "WORKSPACE_SELECTION_REQUIRED: select a workspace folder before starting a swarm run."
+    );
+  }
+  const workspaceRoot = await workspaceExistsAsDirectory(workspaceRootRaw);
+  if (!workspaceRoot) {
+    throw new Error(
+      `Workspace root does not exist or is not a directory: ${resolve(String(workspaceRootRaw || REPO_ROOT))}`
+    );
+  }
+  const maxTasks = Math.max(1, Number.parseInt(String(config.maxTasks || 3), 10) || 3);
+  const maxAgents = Math.max(
+    1,
+    Math.min(16, Number.parseInt(String(config.maxAgents || 3), 10) || 3)
+  );
+  const workflowId =
+    String(config.workflowId || "swarm.blackboard.default").trim() || "swarm.blackboard.default";
+  const verificationMode = normalizeVerificationMode(
+    config?.verificationMode || config?.verification_mode
+  );
+  const requireLlmPlan = config?.requireLlmPlan === true || config?.require_llm_plan === true;
+  const allowLocalPlannerFallback =
+    config?.allowLocalPlannerFallback === true || config?.allow_local_planner_fallback === true;
+  let modelProvider = String(config.modelProvider || "").trim();
+  let modelId = String(config.modelId || "").trim();
+  const mcpServers = (Array.isArray(config.mcpServers) ? config.mcpServers : [])
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean)
+    .slice(0, 64);
+
+  const created = await engineRequestJson(session, "/context/runs", {
+    method: "POST",
+    body: {
+      objective,
+      run_type: "interactive",
+      source_client: "control_panel",
+      model_provider: modelProvider || undefined,
+      model_id: modelId || undefined,
+      mcp_servers: mcpServers,
+      workspace: {
+        workspace_id: buildWorkspaceId(workspaceRoot),
+        canonical_path: workspaceRoot,
+        lease_epoch: 1,
+      },
+    },
+  });
+  const run = created?.run;
+  const runId = String(run?.run_id || "").trim();
+  if (!runId) throw new Error("Context run creation failed (missing run_id).");
+
+  await appendContextRunEvent(session, runId, "planning_started", "planning", {
+    source_client: "control_panel",
+    max_tasks: maxTasks,
+    max_agents: maxAgents,
+    workflow_id: workflowId,
+    verification_mode: verificationMode,
+    model_provider: modelProvider || undefined,
+    model_id: modelId || undefined,
+    mcp_servers: mcpServers,
+  });
+  const synced = (() =>
+    engineRequestJson(session, `/context/runs/${encodeURIComponent(runId)}/todos/sync`, {
+      method: "POST",
+      body: {
+        replace: true,
+        todos: [],
+        source_session_id: null,
+        source_run_id: runId,
+      },
+    }))();
+  await synced;
+  let plannerTasks = [];
+  let planSeedMode = "fallback_local";
+  const enforceStrictTaskOutputs = String(verificationMode || "strict").trim().toLowerCase() === "strict";
+  try {
+    const llmPlan = await generatePlanTodosWithLLM(session, run, maxTasks);
+    let plannerSource = "llm_objective_planner";
+    let plannerNote = "";
+    plannerTasks = ensurePlannerTaskOutputTargets(
+      normalizePlannerTasks(llmPlan.tasks, maxTasks, { linearFallback: false }),
+      objective
+    );
+    if (!plannerTasks.length) {
+      const recovered = fallbackPlannerTasks(objective, maxTasks, llmPlan?.assistantText || "");
+      plannerTasks = ensurePlannerTaskOutputTargets(recovered.tasks, objective);
+      plannerSource = recovered.source;
+      plannerNote = recovered.note;
+    }
+    if (enforceStrictTaskOutputs) {
+      const strictCheck = validateStrictPlannerTasks(plannerTasks);
+      if (!strictCheck.ok) {
+        throw new Error(
+          `STRICT_TASK_PLAN_INVALID: missing_output_target=${strictCheck.missing.join(", ")} invalid_task_kind=${strictCheck.invalidTaskKinds.join(", ")}`
+        );
+      }
+    }
+    const seeded = await seedBlackboardTasks(session, runId, objective, plannerTasks, workflowId);
+    planSeedMode = "blackboard_llm";
+    await appendContextRunEvent(session, runId, "plan_seeded_llm", "planning", {
+      source: plannerSource,
+      session_id: llmPlan.sessionId || null,
+      task_count: Number(seeded?.count || 0),
+      dependency_edges: plannerTasks.reduce(
+        (sum, task) =>
+          sum + (Array.isArray(task?.dependsOnTaskIds) ? task.dependsOnTaskIds.length : 0),
+        0
+      ),
+      workflow_id: workflowId,
+      planner_target: planSeedMode,
+      note: plannerNote || undefined,
+    });
+  } catch (planningError) {
+    const plannerFailureReason = String(
+      planningError?.message || planningError || "unknown planning failure"
+    );
+    const recovered = fallbackPlannerTasks(objective, maxTasks, planningError?.assistantText || "");
+    plannerTasks = ensurePlannerTaskOutputTargets(recovered.tasks, objective);
+    const forcedFallback = requireLlmPlan && !allowLocalPlannerFallback;
+    if (forcedFallback) {
+      await appendContextRunEvent(session, runId, "plan_failed_llm_required", "planning", {
+        reason: plannerFailureReason,
+        recovered: false,
+        recovery_source: recovered.source,
+      }).catch(() => null);
+      throw new Error(`LLM planning failed and fallback is disabled: ${plannerFailureReason}`);
+    }
+    if (enforceStrictTaskOutputs) {
+      const strictCheck = validateStrictPlannerTasks(plannerTasks);
+      if (!strictCheck.ok) {
+        await appendContextRunEvent(session, runId, "plan_failed_output_target_missing", "planning", {
+          reason: plannerFailureReason,
+          missing_tasks: strictCheck.missing,
+          invalid_task_kind_tasks: strictCheck.invalidTaskKinds,
+          recovery_source: recovered.source,
+        }).catch(() => null);
+        throw new Error(
+          `Strict orchestration requires valid task kinds and output targets where needed: missing_output_target=${strictCheck.missing.join(", ")} invalid_task_kind=${strictCheck.invalidTaskKinds.join(", ")}`
+        );
+      }
+    }
+    try {
+      const seeded = await seedBlackboardTasks(session, runId, objective, plannerTasks, workflowId);
+      planSeedMode = "blackboard_local";
+      await appendContextRunEvent(session, runId, "plan_seeded_local", "planning", {
+        source: recovered.source,
+        task_count: Number(seeded?.count || 0),
+        dependency_edges: plannerTasks.reduce(
+          (sum, task) =>
+            sum + (Array.isArray(task?.dependsOnTaskIds) ? task.dependsOnTaskIds.length : 0),
+          0
+        ),
+        workflow_id: workflowId,
+        planner_target: planSeedMode,
+        note: `${recovered.note} Planner fallback used: ${plannerFailureReason}`,
+      });
+    } catch (blackboardError) {
+      throw blackboardError;
+    }
+  }
+  await appendContextRunEvent(session, runId, "plan_ready_for_approval", "awaiting_approval", {
+    source_client: "control_panel",
+    workflow_id: workflowId,
+    max_agents: maxAgents,
+    verification_mode: verificationMode,
+    planner_mode: planSeedMode,
+  });
+  upsertSwarmRunController(runId, {
+    status: "awaiting_approval",
+    startedAt: Date.now(),
+    stoppedAt: null,
+    objective,
+    workspaceRoot,
+    maxTasks,
+    maxAgents,
+    workflowId,
+    modelProvider,
+    modelId,
+    resolvedModelProvider: "",
+    resolvedModelId: "",
+    modelResolutionSource: "deferred",
+    mcpServers,
+    repoRoot: workspaceRoot,
+    verificationMode,
+    lastError: "",
+    executorMode: planSeedMode.startsWith("blackboard") ? "blackboard" : "context_steps",
+    executorState: "idle",
+    executorReason: "",
+    attachedPid: null,
+    registryCache: null,
+  });
+  setActiveSwarmRunId(runId);
+  setSwarmPreflight({
+    gitAvailable: null,
+    repoReady: true,
+    autoInitialized: false,
+    code: "workspace_ready",
+    reason: "",
+    guidance: "",
+  });
+  pushSwarmEvent("status", { status: swarmState.status, runId: runId });
+  return runId;
+}
+
+const handleSwarmApi = createSwarmApiHandler({
+  PORTAL_PORT,
+  REPO_ROOT,
+  ENGINE_URL,
+  swarmState,
+  isLocalEngineUrl,
+  sendJson,
+  readJsonBody,
+  workspaceExistsAsDirectory,
+  loadHiddenSwarmRunIds,
+  saveHiddenSwarmRunIds,
+  engineRequestJson,
+  appendContextRunEvent,
+  contextRunStatusToSwarmStatus,
+  startSwarm,
+  detectExecutorMode,
+  startRunExecutor,
+  requeueInProgressSteps,
+  transitionBlackboardTask,
+  contextRunSnapshot,
+  contextRunToTasks,
+  getSwarmRunController,
+  upsertSwarmRunController,
+  setActiveSwarmRunId,
+});
+
 async function handleApi(req, res) {
   const pathname = new URL(req.url, `http://127.0.0.1:${PORTAL_PORT}`).pathname;
 
@@ -1235,7 +4373,10 @@ async function handleApi(req, res) {
     if (!health) {
       sessions.delete(session.sid);
       clearSessionCookie(res);
-      sendJson(res, 401, { ok: false, error: "Session token is no longer valid for the configured engine." });
+      sendJson(res, 401, {
+        ok: false,
+        error: "Session token is no longer valid for the configured engine.",
+      });
       return true;
     }
     sendJson(res, 200, {
@@ -1247,7 +4388,7 @@ async function handleApi(req, res) {
     return true;
   }
 
-  if (pathname.startsWith("/api/swarm")) {
+  if (pathname.startsWith("/api/swarm") || pathname.startsWith("/api/orchestrator")) {
     const session = requireSession(req, res);
     if (!session) return true;
     return handleSwarmApi(req, res, session);
@@ -1302,7 +4443,6 @@ function shutdown(signal) {
   }
   if (swarmState.process && !swarmState.process.killed) {
     try {
-      clearSwarmMonitor();
       swarmState.process.kill("SIGTERM");
     } catch {}
   }
@@ -1318,6 +4458,13 @@ process.on("SIGINT", () => shutdown("SIGINT"));
 process.on("SIGTERM", () => shutdown("SIGTERM"));
 
 async function main() {
+  if (serviceOp) {
+    await operateServices(serviceOp, serviceMode);
+    if (serviceSetupOnly && !installServicesRequested) {
+      return;
+    }
+  }
+
   if (installServicesRequested) {
     await installServices();
     if (serviceSetupOnly) {
@@ -1352,13 +4499,15 @@ async function main() {
     process.exit(1);
   });
 
-  server.listen(PORTAL_PORT, () => {
+  server.listen(PORTAL_PORT, PANEL_HOST, () => {
     log("=========================================");
-    log(`Control Panel: http://localhost:${PORTAL_PORT}`);
+    log(`Control Panel: http://${PANEL_HOST}:${PORTAL_PORT}`);
+    if (PANEL_PUBLIC_URL) log(`Public URL:    ${PANEL_PUBLIC_URL}`);
     log(`Engine URL:    ${ENGINE_URL}`);
     log(`Engine mode:   ${isLocalEngineUrl(ENGINE_URL) ? "local" : "remote"}`);
     log(`Files root:    ${FILES_ROOT}`);
     log(`Files scope:   ${FILES_SCOPE || "(full root)"}`);
+    log(`Build:         ${CONTROL_PANEL_BUILD_FINGERPRINT}`);
     log("=========================================");
   });
 }