bosun 0.40.21 → 0.41.0

package/agent/agent-custom-tools.mjs

@@ -561,12 +561,30 @@ export async function invokeCustomTool(rootDir, toolId, args = [], opts = {}) {
       timeout,
       maxBuffer: 10 * 1024 * 1024, // 10 MB
     });
-    stdout = out.stdout;
-    stderr = out.stderr;
+    // Node versions/environments may resolve promisified execFile as:
+    // - { stdout, stderr } (modern child_process custom promisify)
+    // - stdout string/buffer only (legacy/mocked fallback)
+    // - [stdout, stderr] tuple (some custom wrappers)
+    if (out && typeof out === "object" && !Array.isArray(out)) {
+      stdout = String(out.stdout ?? "");
+      stderr = String(out.stderr ?? "");
+    } else if (Array.isArray(out)) {
+      stdout = String(out[0] ?? "");
+      stderr = String(out[1] ?? "");
+    } else {
+      stdout = String(out ?? "");
+      stderr = "";
+    }
   } catch (err) {
-    stdout = err.stdout || "";
-    stderr = err.stderr || err.message || "";
-    exitCode = err.code ?? 1;
+    stdout = String(err?.stdout ?? "");
+    stderr = String(err?.stderr ?? err?.message ?? "");
+    const numericExit = Number(err?.code);
+    const numericStatus = Number(err?.status);
+    exitCode = Number.isFinite(numericExit)
+      ? numericExit
+      : Number.isFinite(numericStatus)
+        ? numericStatus
+        : 1;
   }
 
   // Record usage non-blocking

package/agent/agent-pool.mjs

@@ -53,6 +53,7 @@ import {
   streamRetryDelay,
   MAX_STREAM_RETRIES,
 } from "../infra/stream-resilience.mjs";
+import { ensureTestRuntimeSandbox } from "../infra/test-runtime.mjs";
 import { compressAllItems, estimateSavings, estimateContextUsagePct, recordShreddingEvent } from "../workspace/context-cache.mjs";
 import { resolveContextShreddingOptions } from "../config/context-shredding-config.mjs";
 
@@ -2521,7 +2522,10 @@ export async function execPooledPrompt(userMessage, options = {}) {
 /** @type {Map<string, ThreadRecord>} In-memory registry keyed by taskKey */
 const threadRegistry = new Map();
 
-const THREAD_REGISTRY_FILE = resolve(__dirname, "..", "logs", "thread-registry.json");
+const testSandbox = ensureTestRuntimeSandbox();
+const THREAD_REGISTRY_FILE = testSandbox?.cacheDir
+  ? resolve(testSandbox.cacheDir, "thread-registry.json")
+  : resolve(__dirname, "..", "logs", "thread-registry.json");
 const THREAD_MAX_AGE_MS = 12 * 60 * 60 * 1000; // 12 hours
 
 /** Maximum turns before a thread is considered exhausted and must be replaced */
@@ -2707,7 +2711,7 @@ async function loadThreadRegistry() {
 async function saveThreadRegistry() {
   try {
     const { writeFile, mkdir } = await import("node:fs/promises");
-    await mkdir(resolve(__dirname, "..", "logs"), { recursive: true });
+    await mkdir(dirname(THREAD_REGISTRY_FILE), { recursive: true });
     const obj = Object.fromEntries(threadRegistry);
     await writeFile(THREAD_REGISTRY_FILE, JSON.stringify(obj, null, 2), "utf8");
   } catch {

package/agent/primary-agent.mjs

@@ -67,7 +67,9 @@ import {
 import { getModelsForExecutor, normalizeExecutorKey } from "../task/task-complexity.mjs";
 
 /** Valid agent interaction modes */
-const VALID_MODES = ["ask", "agent", "plan", "web", "instant"];
+const CORE_MODES = ["ask", "agent", "plan", "web", "instant"];
+/** Custom modes loaded from library */
+const _customModes = new Map();
 
 const MODE_ALIASES = Object.freeze({
   code: "agent",
@@ -116,7 +118,37 @@ function normalizeAgentMode(rawMode, fallback = "agent") {
   const normalized = String(rawMode || "").trim().toLowerCase();
   if (!normalized) return fallback;
   const mapped = MODE_ALIASES[normalized] || normalized;
-  return VALID_MODES.includes(mapped) ? mapped : fallback;
+  return getValidModes().includes(mapped) ? mapped : fallback;
+}
+
+/**
+ * Get all valid modes including dynamically registered custom modes.
+ * @returns {string[]}
+ */
+function getValidModes() {
+  return [...CORE_MODES, ..._customModes.keys()];
+}
+
+/**
+ * Get mode prefix for a given mode, including custom modes.
+ * @param {string} mode
+ * @returns {string}
+ */
+function getModePrefix(mode) {
+  if (MODE_PREFIXES[mode] !== undefined) return MODE_PREFIXES[mode];
+  const custom = _customModes.get(mode);
+  return custom?.prefix || "";
+}
+
+/**
+ * Get execution policy for a given mode, including custom modes.
+ * @param {string} mode
+ * @returns {object|null}
+ */
+function getModeExecPolicy(mode) {
+  if (MODE_EXEC_POLICIES[mode]) return MODE_EXEC_POLICIES[mode];
+  const custom = _customModes.get(mode);
+  return custom?.execPolicy || null;
 }
 
 function normalizeAttachments(input) {
@@ -908,7 +940,7 @@ export async function execPrimaryPrompt(userMessage, options = {}) {
     (options && options.sessionType ? String(options.sessionType) : "") ||
     "primary";
   const effectiveMode = normalizeAgentMode(options.mode || agentMode, agentMode);
-  const modePolicy = MODE_EXEC_POLICIES[effectiveMode] || null;
+  const modePolicy = getModeExecPolicy(effectiveMode);
   const timeoutMs = options.timeoutMs || modePolicy?.timeoutMs || PRIMARY_EXEC_TIMEOUT_MS;
   const maxFailoverAttempts = Number.isInteger(options.maxFailoverAttempts)
     ? Math.max(0, Number(options.maxFailoverAttempts))
@@ -918,7 +950,7 @@ export async function execPrimaryPrompt(userMessage, options = {}) {
   const attachmentsAppended = options.attachmentsAppended === true;
 
   // Apply mode prefix (options.mode overrides the global setting for this call)
-  const modePrefix = MODE_PREFIXES[effectiveMode] || "";
+  const modePrefix = getModePrefix(effectiveMode);
   const messageWithAttachments = attachments.length && !attachmentsAppended
     ? appendAttachmentsToPrompt(userMessage, attachments).message
     : userMessage;
@@ -1241,8 +1273,8 @@ export function getAgentMode() {
  */
 export function setAgentMode(mode) {
   const normalized = normalizeAgentMode(mode, "");
-  if (!VALID_MODES.includes(normalized)) {
-    return { ok: false, mode: agentMode, error: `Invalid mode "${mode}". Valid: ${VALID_MODES.join(", ")}` };
+  if (!getValidModes().includes(normalized)) {
+    return { ok: false, mode: agentMode, error: `Invalid mode "${mode}". Valid: ${getValidModes().join(", ")}` };
   }
   agentMode = normalized;
   return { ok: true, mode: agentMode };
@@ -1254,10 +1286,52 @@ export function setAgentMode(mode) {
  * @returns {string}
  */
 export function applyModePrefix(userMessage) {
-  const prefix = MODE_PREFIXES[agentMode] || "";
+  const prefix = getModePrefix(agentMode);
   return prefix ? prefix + userMessage : userMessage;
 }
 
+/**
+ * Register a custom interaction mode at runtime.
+ * Core modes cannot be overridden.
+ * @param {string} id
+ * @param {{ prefix?: string, execPolicy?: object|null, toolFilter?: object|null, description?: string }} config
+ */
+export function registerCustomMode(id, config) {
+  if (!id || typeof id !== "string") return;
+  const modeId = id.trim().toLowerCase();
+  if (CORE_MODES.includes(modeId)) return;
+  _customModes.set(modeId, {
+    prefix: config.prefix || "",
+    execPolicy: config.execPolicy || null,
+    toolFilter: config.toolFilter || null,
+    description: config.description || "",
+  });
+}
+
+/**
+ * List all available modes (core + custom) with metadata.
+ * @returns {Array<{id: string, description: string, core: boolean}>}
+ */
+export function listAvailableModes() {
+  const modes = CORE_MODES.map((m) => ({
+    id: m,
+    description: MODE_PREFIXES[m]?.slice(0, 80) || "Full agentic behavior",
+    core: true,
+  }));
+  for (const [id, cfg] of _customModes) {
+    modes.push({ id, description: cfg.description, core: false });
+  }
+  return modes;
+}
+
+/**
+ * Get all registered custom modes.
+ * @returns {Array<{id: string, prefix: string, execPolicy: object|null, toolFilter: object|null, description: string}>}
+ */
+export function getCustomModes() {
+  return [..._customModes.entries()].map(([id, cfg]) => ({ id, ...cfg }));
+}
+
 /**
  * Get the list of available agent adapters with capabilities.
  * @returns {Array<{id:string, name:string, provider:string, available:boolean, busy:boolean, capabilities:object}>}

package/bench/swebench/bosun-swebench.mjs

@@ -217,6 +217,11 @@ export function sha256File(pathLike) {
 
 export function safeGit(args, cwd = process.cwd()) {
   try {
+    // Block dangerous git arguments that could execute arbitrary commands
+    const blocked = ["--upload-pack", "--exec", "-c"];
+    for (const a of args) {
+      if (blocked.some((b) => String(a).startsWith(b))) return "";
+    }
     return execFileSync("git", args, { encoding: "utf8", cwd }).trim();
   } catch {
     return "";

package/cli.mjs

@@ -28,6 +28,7 @@ import { fileURLToPath } from "node:url";
 import { execFileSync, execSync, fork, spawn } from "node:child_process";
 import os from "node:os";
 import { createDaemonCrashTracker } from "./infra/daemon-restart-policy.mjs";
+import { ensureTestRuntimeSandbox } from "./infra/test-runtime.mjs";
 import {
   applyAllCompatibility,
   detectLegacySetup,
@@ -140,6 +141,12 @@ function showHelp() {
     --workspace-switch <id>     Switch active workspace
     --workspace-add-repo        Add repo to workspace (interactive)
     --workspace-health          Run workspace health diagnostics
+    --workspace-pause <id>      Pause a workspace (no new workflows)
+    --workspace-resume <id>     Resume a paused workspace
+    --workspace-disable <id>    Disable a workspace entirely
+    --workspace-status          Show state summary of all workspaces
+    --workspace-executors <id>  Show/set executor config for workspace
+                                  [--max-concurrent N] [--pool shared|dedicated] [--weight N]
 
   TASK MANAGEMENT
     task list [--status s] [--json]  List tasks with optional filters
@@ -252,6 +259,9 @@ function resolveConfigDirForCli() {
   const repoLocalConfigDir = resolveRepoLocalBosunDir(repoRoot);
   if (repoLocalConfigDir) return repoLocalConfigDir;
 
+  const sandbox = ensureTestRuntimeSandbox();
+  if (sandbox?.configDir) return sandbox.configDir;
+
   const preferWindowsDirs =
     process.platform === "win32" && !isWslInteropRuntime();
   const baseDir = preferWindowsDirs
@@ -368,10 +378,21 @@ function uniqueResolvedPaths(paths) {
   return results;
 }
 
+function getWorkspaceScopedCacheDirCandidate(repoRootPath) {
+  const bosunDir = process.env.BOSUN_DIR || resolveConfigDirForCli();
+  if (!bosunDir || !repoRootPath) return null;
+  const parts = String(repoRootPath).replace(/\\/g, "/").split("/").filter(Boolean);
+  const repoName = parts.at(-1);
+  const workspaceName = parts.at(-2);
+  if (!repoName || !workspaceName) return null;
+  return resolve(bosunDir, "workspaces", workspaceName, repoName, ".cache");
+}
+
 function getRuntimeCacheDirCandidates(extraCacheDirs = []) {
   return uniqueResolvedPaths([
     ...extraCacheDirs,
     runtimeCacheDir,
+    getWorkspaceScopedCacheDirCandidate(runtimeRepoRoot),
     process.env.BOSUN_DIR ? resolve(process.env.BOSUN_DIR, ".cache") : null,
     resolve(__dirname, ".cache"),
     resolve(process.cwd(), ".cache"),
@@ -625,6 +646,42 @@ function findGhostDaemonPids() {
   }
 }
 
+function findGhostSentinelPids() {
+  if (process.platform === "win32") {
+    try {
+      const out = execFileSync(
+        "powershell",
+        [
+          "-NoProfile",
+          "-Command",
+          "Get-CimInstance Win32_Process | Where-Object { $_.Name -match '^(node|electron)(\\.exe)?$' -and $_.CommandLine -match 'telegram-sentinel\\.mjs' } | Select-Object -ExpandProperty ProcessId",
+        ],
+        { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 3000 },
+      ).trim();
+      if (!out) return [];
+      return out
+        .split(/\r?\n/)
+        .map((s) => parseInt(String(s).trim(), 10))
+        .filter((n) => Number.isFinite(n) && n > 0 && n !== process.pid);
+    } catch {
+      return [];
+    }
+  }
+  try {
+    const out = execFileSync(
+      "pgrep",
+      ["-f", "telegram-sentinel\\.mjs"],
+      { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 3000 },
+    ).trim();
+    return out
+      .split("\n")
+      .map((s) => parseInt(s.trim(), 10))
+      .filter((n) => Number.isFinite(n) && n > 0 && n !== process.pid);
+  } catch {
+    return [];
+  }
+}
+
 function writePidFile(pid) {
   try {
     mkdirSync(dirname(DAEMON_PID_FILE), { recursive: true });
@@ -852,10 +909,14 @@ function daemonStatus() {
   } else {
     // Check for ghost daemon-child processes (alive but no PID file)
     const ghosts = findGhostDaemonPids();
+    const ghostSentinels = findGhostSentinelPids();
     if (ghosts.length > 0) {
       console.log(`  :alert:  bosun daemon is NOT tracked (no PID file), but ${ghosts.length} ghost process(es) found: ${ghosts.join(", ")}`);
       console.log(`  The daemon is likely running but its PID file was lost.`);
-      console.log(`  Run --stop-daemon to clean up, then --daemon to restart.`);
+      if (ghostSentinels.length > 0) {
+        console.log(`  Ghost sentinel restart owner(s) detected: ${ghostSentinels.join(", ")}`);
+      }
+      console.log(`  Run --terminate to stop restart owners, then --daemon to restart.`);
     } else {
       // Broader scan: portal, monitor, ui-server, etc. (non-daemon bosun processes)
       const allPids = findAllBosunProcessPids();
@@ -1108,6 +1169,7 @@ async function terminateBosun() {
     ]).map((pidFile) => readAlivePid(pidFile)),
     readSentinelPid(),
   ].filter((pid) => Number.isFinite(pid) && pid > 0);
+  const sentinelGhostPids = findGhostSentinelPids();
   const manualStopHoldMs =
     Math.max(
       0,
@@ -1119,9 +1181,17 @@ async function terminateBosun() {
     ...daemonPids,
     ...monitorPids,
     ...sentinelPids,
+    ...sentinelGhostPids,
+    ...ghosts,
   ]);
   const restartOwnerPids = Array.from(
-    new Set([...ancestorPids, ...sentinelPids, ...daemonPids, ...ghosts]),
+    new Set([
+      ...ancestorPids,
+      ...sentinelPids,
+      ...sentinelGhostPids,
+      ...daemonPids,
+      ...ghosts,
+    ]),
   ).filter((pid) => pid !== process.pid);
   const tracked = [...restartOwnerPids, ...monitorPids];
   const trackedPids = Array.from(new Set([...tracked, ...ghosts])).filter(
@@ -1742,7 +1812,11 @@ async function main() {
       console.log("\n  Workspaces:");
       for (const ws of workspaces) {
         const marker = ws.id === active?.id ? " ← active" : "";
-        console.log(`    ${ws.name} (${ws.id})${marker}`);
+        const stateIcon = ws.state === "active" ? "●" : ws.state === "paused" ? "◐" : "○";
+        const stateLabel = ws.state !== "active" ? ` [${ws.state}]` : "";
+        console.log(`    ${stateIcon} ${ws.name} (${ws.id})${stateLabel}${marker}`);
+        const ex = ws.executors;
+        console.log(`      executors: max=${ex.maxConcurrent}, pool=${ex.pool}, weight=${ex.weight}`);
         for (const repo of ws.repos || []) {
           const primary = repo.primary ? " [primary]" : "";
           const exists = repo.exists ? "✓" : "✗";
@@ -1831,6 +1905,137 @@ async function main() {
     process.exit(result.ok ? 0 : 1);
   }
 
+  // Handle --workspace-pause
+  if (args.includes("--workspace-pause") || args.includes("workspace-pause")) {
+    const { pauseWorkspace, getWorkspace } = await import("./workspace/workspace-manager.mjs");
+    const configDirArg = getArgValue("--config-dir");
+    const configDir = configDirArg || process.env.BOSUN_DIR || resolveConfigDirForCli();
+    const wsId = getArgValue("--workspace-pause") || getArgValue("workspace-pause");
+    if (!wsId) {
+      console.error("  Error: workspace ID required. Usage: bosun --workspace-pause <id>");
+      process.exit(1);
+    }
+    try {
+      pauseWorkspace(configDir, wsId);
+      const ws = getWorkspace(configDir, wsId);
+      console.log(`\n  ⏸  Workspace "${ws?.name || wsId}" paused — no new workflows will start\n`);
+    } catch (err) {
+      console.error(`  Error: ${err.message}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  // Handle --workspace-resume
+  if (args.includes("--workspace-resume") || args.includes("workspace-resume")) {
+    const { resumeWorkspace, getWorkspace } = await import("./workspace/workspace-manager.mjs");
+    const configDirArg = getArgValue("--config-dir");
+    const configDir = configDirArg || process.env.BOSUN_DIR || resolveConfigDirForCli();
+    const wsId = getArgValue("--workspace-resume") || getArgValue("workspace-resume");
+    if (!wsId) {
+      console.error("  Error: workspace ID required. Usage: bosun --workspace-resume <id>");
+      process.exit(1);
+    }
+    try {
+      resumeWorkspace(configDir, wsId);
+      const ws = getWorkspace(configDir, wsId);
+      console.log(`\n  ▶  Workspace "${ws?.name || wsId}" resumed — workflows will trigger normally\n`);
+    } catch (err) {
+      console.error(`  Error: ${err.message}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  // Handle --workspace-disable
+  if (args.includes("--workspace-disable") || args.includes("workspace-disable")) {
+    const { disableWorkspace, getWorkspace } = await import("./workspace/workspace-manager.mjs");
+    const configDirArg = getArgValue("--config-dir");
+    const configDir = configDirArg || process.env.BOSUN_DIR || resolveConfigDirForCli();
+    const wsId = getArgValue("--workspace-disable") || getArgValue("workspace-disable");
+    if (!wsId) {
+      console.error("  Error: workspace ID required. Usage: bosun --workspace-disable <id>");
+      process.exit(1);
+    }
+    try {
+      disableWorkspace(configDir, wsId);
+      const ws = getWorkspace(configDir, wsId);
+      console.log(`\n  ⏹  Workspace "${ws?.name || wsId}" disabled — no workflows, no executors\n`);
+    } catch (err) {
+      console.error(`  Error: ${err.message}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  // Handle --workspace-status
+  if (args.includes("--workspace-status") || args.includes("workspace-status")) {
+    const { getWorkspaceStateSummary } = await import("./workspace/workspace-manager.mjs");
+    const configDirArg = getArgValue("--config-dir");
+    const configDir = configDirArg || process.env.BOSUN_DIR || resolveConfigDirForCli();
+    const summary = getWorkspaceStateSummary(configDir);
+    if (summary.length === 0) {
+      console.log("\n  No workspaces configured.\n");
+    } else {
+      console.log("\n  Workspace Status:");
+      for (const ws of summary) {
+        const stateIcon = ws.state === "active" ? "●" : ws.state === "paused" ? "◐" : "○";
+        const current = ws.isCurrent ? " ← current" : "";
+        console.log(`    ${stateIcon} ${ws.name} (${ws.id}) — ${ws.state}${current}`);
+        const ex = ws.executors;
+        console.log(`      executors: max=${ex.maxConcurrent}, pool=${ex.pool}, weight=${ex.weight}`);
+        if (ws.disabledWorkflows.length > 0) {
+          console.log(`      disabled workflows: ${ws.disabledWorkflows.join(", ")}`);
+        }
+        if (ws.enabledWorkflows.length > 0) {
+          console.log(`      enabled workflows: ${ws.enabledWorkflows.join(", ")}`);
+        }
+      }
+      console.log("");
+    }
+    process.exit(0);
+  }
+
+  // Handle --workspace-executors
+  if (args.includes("--workspace-executors") || args.includes("workspace-executors")) {
+    const { setWorkspaceExecutors, getWorkspace } = await import("./workspace/workspace-manager.mjs");
+    const configDirArg = getArgValue("--config-dir");
+    const configDir = configDirArg || process.env.BOSUN_DIR || resolveConfigDirForCli();
+    const wsId = getArgValue("--workspace-executors") || getArgValue("workspace-executors");
+    if (!wsId) {
+      console.error("  Error: workspace ID required. Usage: bosun --workspace-executors <id> [--max-concurrent N] [--pool shared|dedicated] [--weight N]");
+      process.exit(1);
+    }
+    const maxConcurrent = getArgValue("--max-concurrent");
+    const pool = getArgValue("--pool");
+    const weight = getArgValue("--weight");
+    const hasUpdate = maxConcurrent || pool || weight;
+    if (hasUpdate) {
+      try {
+        const opts = {};
+        if (maxConcurrent) opts.maxConcurrent = Number(maxConcurrent);
+        if (pool) opts.pool = pool;
+        if (weight) opts.weight = Number(weight);
+        const result = setWorkspaceExecutors(configDir, wsId, opts);
+        console.log(`\n  ✓ Executor config updated for "${wsId}":`, JSON.stringify(result), "\n");
+      } catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+      }
+    } else {
+      const ws = getWorkspace(configDir, wsId);
+      if (!ws) {
+        console.error(`  Error: workspace "${wsId}" not found`);
+        process.exit(1);
+      }
+      console.log(`\n  Executor config for "${ws.name}":`);
+      console.log(`    maxConcurrent: ${ws.executors.maxConcurrent}`);
+      console.log(`    pool: ${ws.executors.pool}`);
+      console.log(`    weight: ${ws.executors.weight}\n`);
+    }
+    process.exit(0);
+  }
+
   // Handle --setup-terminal (legacy terminal wizard)
   if (args.includes("--setup-terminal")) {
     const configDirArg = getArgValue("--config-dir");

package/config/config-doctor.mjs

@@ -1,8 +1,10 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { resolve, dirname, isAbsolute, relative, join } from "node:path";
 import { execSync, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+import { ensureTestRuntimeSandbox } from "../infra/test-runtime.mjs";
+import { getWorkflowContract } from "../workflow/workflow-contract.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CONFIG_FILES = [
@@ -10,6 +12,10 @@ const CONFIG_FILES = [
   ".bosun.json",
   "bosun.json",
 ];
+const WORKFLOW_CONTRACT_NODE_TYPES = Object.freeze({
+  read: new Set(["read-workflow-contract", "action.read_workflow_contract"]),
+  validate: new Set(["workflow-contract-validation", "action.workflow_contract_validation"]),
+});
 
 function parseBool(value) {
   return ["1", "true", "yes", "on"].includes(
@@ -92,6 +98,9 @@ function resolveConfigDir(repoRoot) {
     return packageDir;
   }
 
+  const sandbox = ensureTestRuntimeSandbox();
+  if (sandbox?.configDir) return sandbox.configDir;
+
   const preferWindowsDirs =
     process.platform === "win32" && !isWslInteropRuntime();
   const baseDir =
@@ -166,6 +175,36 @@ function findConfigFile(configDir) {
   return null;
 }
 
+function workflowHasContractNodes(definition) {
+  const nodes = Array.isArray(definition?.nodes) ? definition.nodes : [];
+  let hasRead = false;
+  let hasValidate = false;
+  for (const node of nodes) {
+    const type = String(node?.type || "").trim();
+    if (WORKFLOW_CONTRACT_NODE_TYPES.read.has(type)) hasRead = true;
+    if (WORKFLOW_CONTRACT_NODE_TYPES.validate.has(type)) hasValidate = true;
+  }
+  return hasRead && hasValidate;
+}
+
+function hasEnabledWorkflowContractStep(repoRoot) {
+  const workflowDir = resolve(repoRoot, ".bosun", "workflows");
+  if (!existsSync(workflowDir)) return false;
+
+  for (const file of readdirSync(workflowDir)) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const definition = JSON.parse(readFileSync(resolve(workflowDir, file), "utf8"));
+      if (definition?.enabled === false) continue;
+      if (workflowHasContractNodes(definition)) return true;
+    } catch {
+      /* ignore malformed workflow files here; other checks can catch them */
+    }
+  }
+
+  return false;
+}
+
 function validateExecutors(raw, issues) {
   if (!raw) return;
   const entries = String(raw)
@@ -671,6 +710,17 @@ export function runConfigDoctor(options = {}) {
     });
   }
 
+  const workflowContract = getWorkflowContract(repoRoot);
+  if (workflowContract.found && !hasEnabledWorkflowContractStep(repoRoot)) {
+    issues.warnings.push({
+      code: "WORKFLOW_CONTRACT_STEP_DISABLED",
+      message:
+        "WORKFLOW.md exists but no enabled workflow includes the read/validate workflow-contract steps.",
+      fix:
+        "Install or update the session-start workflow (for example template-task-lifecycle) so it includes `read-workflow-contract` and `workflow-contract-validation`.",
+    });
+  }
+
   issues.infos.push({
     code: "PATHS",
     message: `Config directory: ${configDir}`,
@@ -988,4 +1038,3 @@ export function formatWorkspaceHealthReport(result) {
   return lines.join("\n");
 }
 
-