bosun 0.42.5 → 0.43.0

package/.env.example

@@ -1,3 +1,6 @@
+# Max characters of matched built-in/local skills injected into an agent task prompt.
+# Skills are only injected when task title/description/labels match skill tags.
+BOSUN_SKILLS_MAX_CHARS=4000
 # ─── Bosun — Environment Configuration ───────────────────────────────
 # Copy this file to .env and fill in your values.
 # Or run: bosun --setup
@@ -350,12 +353,8 @@ VOICE_DELEGATE_EXECUTOR=codex-sdk
 # FAILOVER_DISABLE_AFTER=3
 
 # ─── Internal Executor ───────────────────────────────────────────────────────
-# Controls whether tasks are executed locally via agent-pool instead of
-# (or alongside) VK's cloud executor. Modes:
-#   "vk"       — all tasks via VK executor (default, existing behavior)
-#   "internal"  — all tasks via local agent-pool (bypass wrapper orchestrator script)
-#   "hybrid"    — both VK and internal run simultaneously for overflow
-# EXECUTOR_MODE=vk
+# Controls whether tasks are executed locally via agent-pool.
+# EXECUTOR_MODE=internal
 # Max concurrent agent slots for internal executor (default: 3)
 # INTERNAL_EXECUTOR_PARALLEL=3
 # INTERNAL_EXECUTOR_BASE_BRANCH_PARALLEL=0
@@ -381,6 +380,12 @@ VOICE_DELEGATE_EXECUTOR=codex-sdk
 # INTERNAL_EXECUTOR_REVIEW_TIMEOUT_MS=300000
 # Experimental autonomous backlog replenishment (disabled by default)
 # INTERNAL_EXECUTOR_REPLENISH_ENABLED=false
+# Enable deterministic internal harness compile/activate control-plane support
+# BOSUN_HARNESS_ENABLED=false
+# Path to harness profile source (JSON or markdown fenced JSON)
+# BOSUN_HARNESS_SOURCE=.bosun/harness/internal-harness.md
+# Validation mode: off | report | enforce
+# BOSUN_HARNESS_VALIDATION_MODE=report
 # Minimum follow-up tasks to generate per completed task (1-2)
 # INTERNAL_EXECUTOR_REPLENISH_MIN_NEW_TASKS=1
 # Maximum follow-up tasks to generate per completed task (1-3)
@@ -495,9 +500,9 @@ VOICE_DELEGATE_EXECUTOR=codex-sdk
 # ─── Kanban Backend ──────────────────────────────────────────────────────────
 # Task-board backend:
 #   internal - local task-store source of truth (recommended primary)
-#   vk      - Vibe-Kanban (secondary adapter)
 #   github  - GitHub Issues
 #   jira    - Jira Issues
+#   gnap    - GNAP projection backend (off by default)
 # KANBAN_BACKEND=internal
 # Sync behavior:
 #   internal-primary - internal task-store remains source-of-truth (recommended)
@@ -598,6 +603,20 @@ VOICE_DELEGATE_EXECUTOR=codex-sdk
 # Optional JSON custom field to store full shared state payload
 # JIRA_CUSTOM_FIELD_SHARED_STATE=customfield_10048
 
+# GNAP backend (KANBAN_BACKEND=gnap)
+# Master toggle for GNAP integration. Must be enabled before selecting gnap.
+# GNAP_ENABLED=false
+# Path to the repo or clone that will host GNAP projection data
+# GNAP_REPO_PATH=
+# Synchronization mode. Bosun currently supports projection-only GNAP wiring.
+# GNAP_SYNC_MODE=projection
+# Where to store GNAP run metadata: git|local
+# GNAP_RUN_STORAGE=git
+# Where to store GNAP message projections: off|git|local
+# GNAP_MESSAGE_STORAGE=off
+# Optional sanitized roadmap export for shared visibility
+# GNAP_PUBLIC_ROADMAP_ENABLED=false
+
 # ─── Sandbox Policy ──────────────────────────────────────────────────────────
 # Controls agent sandbox isolation when using Codex SDK.
 # Options:
@@ -661,37 +680,6 @@ VOICE_DELEGATE_EXECUTOR=codex-sdk
 # Stop auto-restarts after this many instant failures in a row (default: 3)
 # BOSUN_DAEMON_MAX_INSTANT_RESTARTS=3
 
-# ─── Vibe-Kanban ──────────────────────────────────────────────────────────────
-# Base URL for the Vibe-Kanban API (default: http://127.0.0.1:54089)
-VK_BASE_URL=http://127.0.0.1:54089
-# Alternate endpoint URL for VK (overrides VK_BASE_URL if set)
-# VK_ENDPOINT_URL=http://127.0.0.1:54089
-# Port for vibe-kanban API (default: 54089)
-VK_RECOVERY_PORT=54089
-# Host for VK recovery (default: 0.0.0.0)
-# VK_RECOVERY_HOST=0.0.0.0
-# VK_HOST=0.0.0.0
-# Public URL shown in Telegram links (optional)
-# VK_PUBLIC_URL=https://kanban.yoursite.com
-# VK_WEB_URL=https://kanban.yoursite.com
-# VK HTTP timeout/retry controls (used by ve-kanban.ps1)
-# VK_HTTP_TIMEOUT_SEC=45
-# VK_HTTP_RETRIES=2
-# VK_HTTP_RETRY_DELAY_MS=1500
-# Set to true to prevent the monitor from spawning vibe-kanban automatically
-# VK_NO_SPAWN=false
-# Cooldown minutes between VK recovery attempts (default: 10)
-# VK_RECOVERY_COOLDOWN_MIN=10
-# VK health check interval in ms (default: 60000)
-# VK_ENSURE_INTERVAL=60000
-# VK project name (auto-detected)
-# VK_PROJECT_NAME=my-project
-# Explicit VK project/repo IDs (auto-detected if empty)
-# VK_PROJECT_ID=
-# VK_REPO_ID=
-# Override task URL template (optional)
-# VK_TASK_URL_TEMPLATE=https://kanban.yoursite.com/projects/{projectId}/tasks/{taskId}
-
 # ─── Shared Workspace Registry ───────────────────────────────────────────────
 # Optional registry path for shared workspace leasing
 # VE_SHARED_WORKSPACE_REGISTRY=.cache/bosun/shared-workspaces.json
@@ -713,13 +701,8 @@ VK_RECOVERY_PORT=54089
 # GITHUB_TOKEN=
 # GH_TOKEN=
 # GITHUB_PAT=
-# Owner/repo for gh CLI in ve-kanban
-# GH_OWNER=virtengine
-# GH_REPO=virtengine
 # Target branch for PR checks/merge (default: origin/main)
-# VK_TARGET_BRANCH=origin/main
-# Default upstream/base branch for bosun tasks (overrides VK_TARGET_BRANCH)
-# BOSUN_TASK_UPSTREAM=origin/ve/bosun-generic
+# BOSUN_TASK_UPSTREAM=origin/main
 
 # ─── Codex / AI Provider ─────────────────────────────────────────────────────
 # The Codex SDK uses OpenAI-compatible configuration that has been setup in ~/.codex/config.toml -
@@ -1024,7 +1007,7 @@ COPILOT_CLOUD_DISABLED=true
 
 # ─── Task Planner ─────────────────────────────────────────────────────────────
 # How to plan new tasks when backlog is empty:
-#   "kanban"   - (default) create a VK planning task for an agent to refine
+#   "kanban"   - (default) create a planning task for an agent to refine
 #   "codex-sdk" - run Codex SDK directly to generate tasks
 #   "disabled"  - do nothing, wait for manual task creation
 # TASK_PLANNER_MODE=kanban
@@ -1056,6 +1039,8 @@ COPILOT_CLOUD_DISABLED=true
 # WORKFLOW_RECOVERY_BACKOFF_MAX_MS=60000
 # Random jitter ratio (0.0-0.9) applied to backoff to prevent retry storms.
 # WORKFLOW_RECOVERY_BACKOFF_JITTER_RATIO=0.2
+# Delay startup interrupted-run replay so the UI/API can become responsive first.
+# WORKFLOW_STARTUP_HISTORY_RECOVERY_DELAY_MS=120000
 
 # ─── GitHub Issue Reconciler ─────────────────────────────────────────────────
 # Periodically reconciles open GitHub issues against open/merged PRs.
@@ -1135,12 +1120,15 @@ COPILOT_CLOUD_DISABLED=true
 # Repository root (auto-detected from git; setup writes this)
 # REPO_ROOT=/path/to/repo
 # Watch path to trigger restarts (default: script path)
-# WATCH_PATH=/path/to/ve-orchestrator.sh
+# WATCH_PATH=/path/to/orchestrator.sh
 # Monitor source hot-reload watcher. Default: enabled in devmode, disabled otherwise.
 # Set to true to force-enable monitor source hot-restart, false to force-disable.
 # SELF_RESTART_WATCH_ENABLED=true
-# Status file path (default: .cache/ve-orchestrator-status.json)
-# STATUS_FILE=.cache/ve-orchestrator-status.json
+# Quiet period after the last source-file change before self-restart is allowed.
+# Default: 180000 (3 minutes)
+# SELF_RESTART_QUIET_MS=180000
+# Status file path (default: .cache/orchestrator-status.json)
+# STATUS_FILE=.cache/orchestrator-status.json
 # Log directory (default: ./logs)
 # LOG_DIR=./logs
 # Max total log folder size in MB. Oldest logs are deleted when exceeded. 0 = unlimited.
@@ -1161,8 +1149,6 @@ COPILOT_CLOUD_DISABLED=true
 # AGENT_WORK_LOGGING_ENABLED=true
 # Enable/disable live stream analyzer (default: true)
 # AGENT_WORK_ANALYZER_ENABLED=true
-# Enrich missing task metadata from VK for agent work logs (default: true)
-# AGENT_WORK_LOGGING_ENRICH_VK=true
 # Task metadata cache (auto-managed): .cache/agent-work-logs/task-metadata.json
 # Log directory (default: .cache/agent-work-logs)
 # AGENT_WORK_LOG_DIR=.cache/agent-work-logs
@@ -1183,4 +1169,3 @@ COPILOT_CLOUD_DISABLED=true
 
 # OpenTelemetry tracing (optional)
 # BOSUN_OTEL_ENDPOINT=http://localhost:4318/v1/traces
-

package/README.md

@@ -65,7 +65,7 @@ Open `https://localhost:3080` to start the setup wizard.
 
 Requires:
 
-- Node.js 18+
+- Node.js 22.13+
 - Git
 - Bash (for `.sh` wrappers) or PowerShell 7+ (for `.ps1` wrappers)
 - GitHub CLI (`gh`) recommended
@@ -108,7 +108,7 @@ Fallback admin auth (secondary path) is available and stores only Argon2id hash
 - Persists workflow runs to disk and auto-resumes on restart
 - Monitors runs and recovers from stalled or broken states
 - Provides Telegram control and a Mini App dashboard
-- Integrates with GitHub, Jira, and Vibe-Kanban boards
+- Integrates with GitHub and Jira boards
 
 ## Autonomous Engineer Workflow Capabilities
 
@@ -162,6 +162,20 @@ Key places to start:
 - `docs/agent-logging-quickstart.md` - agent work logging quickstart
 - `docs/agent-work-logging-design.md` - logging design and event model
 
+## Troubleshooting
+
+### Preflight warns about an interactive git editor
+
+If preflight reports an interactive git editor such as `code --wait`, `vim`, or `nano`, Bosun can deadlock while Git waits for an editor session to close.
+
+Run this from the repo root to switch the local repo config to a non-interactive editor:
+
+```bash
+node git-editor-fix.mjs
+```
+
+Preflight checks both `GIT_EDITOR` and `git config --get core.editor`. No warning is shown when `core.editor` is already non-interactive, for example `:`.
+
 ---
 
 ## CI/CD and quality gates
@@ -228,7 +242,7 @@ npm run hooks:install
 - `server/` — setup server, Mini App backend, and API endpoints
 - `ui/` — Mini App frontend assets and operator dashboard modules
 - `telegram/` — Telegram bot, sentinel, and channel integrations
-- `github/` and `kanban/` — GitHub auth/webhooks and Vibe-Kanban adapters
+- `github/` and `kanban/` — GitHub auth/webhooks and kanban adapters
 - `workspace/` — shared workspace registry, context indexing, and worktree lifecycle
 - `shell/` and `agent/` — executor integrations, prompts, hooks, and fleet coordination
 - `site/` — marketing site and generated docs website assets
@@ -251,3 +265,5 @@ If you find this project useful or would like to stay up to date with new releas
 ## License
 
 Apache-2.0
+
+

package/agent/agent-custom-tools.mjs

@@ -47,7 +47,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { copyFile, writeFile } from "node:fs/promises";
+import { copyFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -212,7 +212,10 @@ function safeReadIndex(storeDir) {
   if (!existsSync(idx)) return [];
   try {
     const parsed = JSON.parse(readFileSync(idx, "utf8"));
-    return Array.isArray(parsed) ? parsed : [];
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .map((entry) => sanitizeIndexEntry(entry))
+      .filter(Boolean);
   } catch {
     return [];
   }
@@ -243,6 +246,77 @@ function scriptPath(storeDir, id, lang) {
   return resolve(storeDir, `${id}.${lang}`);
 }
 
+function isPlainObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeStringList(values, { lowercase = true } = {}) {
+  if (!Array.isArray(values)) return [];
+  const normalized = values
+    .map((value) => String(value ?? "").trim())
+    .filter(Boolean)
+    .map((value) => (lowercase ? value.toLowerCase() : value));
+  return Array.from(new Set(normalized));
+}
+
+function normalizeUsageCount(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric >= 0 ? numeric : 0;
+}
+
+function normalizeToolId(toolId) {
+  if (typeof toolId !== "string") return null;
+  const trimmed = toolId.trim();
+  if (!trimmed) return null;
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$/.test(trimmed)) return null;
+  return trimmed;
+}
+
+function sanitizeIndexEntry(raw) {
+  if (!isPlainObject(raw)) return null;
+
+  const id = normalizeToolId(raw.id);
+  const lang = VALID_LANGS.includes(raw.lang) ? raw.lang : null;
+  if (!id || !lang) return null;
+
+  const category = TOOL_CATEGORIES.includes(raw.category)
+    ? raw.category
+    : "utility";
+  const skills = normalizeStringList(raw.skills, { lowercase: false });
+  const agents = normalizeStringList(raw.agents, { lowercase: false });
+  const templates = normalizeStringList(raw.templates, { lowercase: false });
+
+  return {
+    ...raw,
+    id,
+    title: typeof raw.title === "string" && raw.title.trim() ? raw.title : id,
+    description: typeof raw.description === "string" ? raw.description : "",
+    tags: normalizeStringList(raw.tags),
+    category,
+    lang,
+    createdBy: typeof raw.createdBy === "string" && raw.createdBy.trim()
+      ? raw.createdBy
+      : "agent",
+    createdAt: typeof raw.createdAt === "string" && raw.createdAt.trim()
+      ? raw.createdAt
+      : nowISO(),
+    updatedAt: typeof raw.updatedAt === "string" && raw.updatedAt.trim()
+      ? raw.updatedAt
+      : nowISO(),
+    usageCount: normalizeUsageCount(raw.usageCount),
+    ...(typeof raw.lastUsed === "string" && raw.lastUsed.trim()
+      ? { lastUsed: raw.lastUsed }
+      : {}),
+    ...(skills.length > 0 ? { skills } : {}),
+    ...(agents.length > 0 ? { agents } : {}),
+    ...(templates.length > 0 ? { templates } : {}),
+    ...(raw.autoInject ? { autoInject: true } : {}),
+    ...(typeof raw.version === "string" && raw.version.trim()
+      ? { version: raw.version }
+      : {}),
+  };
+}
+
 // ── Types ─────────────────────────────────────────────────────────────────────
 
 /**
@@ -302,6 +376,9 @@ export function listCustomTools(rootDir, opts = {}) {
     includeBuiltins = true,
   } = opts;
 
+  const requestedTags = normalizeStringList(tags);
+  const searchQuery = typeof search === "string" ? search.trim().toLowerCase() : "";
+
   let entries = [];
 
   // Workspace tools
@@ -339,23 +416,24 @@ export function listCustomTools(rootDir, opts = {}) {
   if (category) {
     entries = entries.filter((e) => e.category === category);
   }
-  if (tags.length > 0) {
+  if (requestedTags.length > 0) {
     entries = entries.filter((e) =>
-      tags.some((t) => (e.tags || []).includes(t)),
+      requestedTags.some((t) => (e.tags || []).includes(t)),
     );
   }
-  if (search) {
-    const q = search.toLowerCase();
+  if (searchQuery) {
     entries = entries.filter(
       (e) =>
-        e.id.includes(q) ||
-        e.title.toLowerCase().includes(q) ||
-        e.description.toLowerCase().includes(q) ||
-        (e.tags || []).some((t) => t.includes(q)),
+        e.id.toLowerCase().includes(searchQuery) ||
+        e.title.toLowerCase().includes(searchQuery) ||
+        e.description.toLowerCase().includes(searchQuery) ||
+        (e.tags || []).some((t) => t.toLowerCase().includes(searchQuery)),
     );
   }
 
-  return entries.sort((a, b) => b.usageCount - a.usageCount);
+  return entries.sort(
+    (a, b) => normalizeUsageCount(b.usageCount) - normalizeUsageCount(a.usageCount),
+  );
 }
 
 /**
@@ -366,11 +444,14 @@ export function listCustomTools(rootDir, opts = {}) {
  * @returns {{ entry: CustomToolEntry, script: string }|null}
  */
 export function getCustomTool(rootDir, toolId) {
+  const normalizedToolId = normalizeToolId(toolId);
+  if (!normalizedToolId) return null;
+
   // Workspace-scoped takes precedence, then global, then builtin
   for (const isGlobal of [false, true]) {
     const storeDir = getToolStore(rootDir, { global: isGlobal });
     const index = safeReadIndex(storeDir);
-    const entry = index.find((e) => e.id === toolId);
+    const entry = index.find((e) => e.id === normalizedToolId);
     if (!entry) continue;
 
     const sPath = scriptPath(storeDir, entry.id, entry.lang);
@@ -383,7 +464,7 @@ export function getCustomTool(rootDir, toolId) {
   }
 
   // Fall back to built-in tools shipped with bosun
-  const builtinDef = BUILTIN_TOOLS.find((b) => b.id === toolId);
+  const builtinDef = BUILTIN_TOOLS.find((b) => b.id === normalizedToolId);
   if (builtinDef) {
     const sPath = resolve(BUILTIN_TOOLS_DIR, `${builtinDef.id}.${builtinDef.lang}`);
     if (existsSync(sPath)) {
@@ -414,6 +495,10 @@ export function getCustomTool(rootDir, toolId) {
  * @returns {CustomToolEntry}
  */
 export function registerCustomTool(rootDir, def) {
+  if (!isPlainObject(def)) {
+    throw new TypeError("registerCustomTool: definition object is required");
+  }
+
   const {
     title,
     description,
@@ -449,19 +534,29 @@ export function registerCustomTool(rootDir, def) {
     );
   }
 
+  const explicitId = def.id == null ? null : normalizeToolId(def.id);
+  if (def.id != null && !explicitId) {
+    throw new TypeError(
+      "registerCustomTool: id must match /^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$/ and must not contain path separators",
+    );
+  }
+
   const storeDir = getToolStore(rootDir, { global: isGlobal });
   const index = safeReadIndex(storeDir);
 
-  const id = def.id || slugify(title) || `tool-${Date.now()}`;
+  const id = explicitId || slugify(title) || `tool-${Date.now()}`;
   const existingIdx = index.findIndex((e) => e.id === id);
   const now = nowISO();
+  const normalizedSkills = normalizeStringList(skills, { lowercase: false });
+  const normalizedAgents = normalizeStringList(agents, { lowercase: false });
+  const normalizedTemplates = normalizeStringList(templates, { lowercase: false });
 
   /** @type {CustomToolEntry} */
   const entry = {
     id,
     title,
     description: description || "",
-    tags: Array.from(new Set(tags.map((t) => String(t).toLowerCase()))),
+    tags: normalizeStringList(tags),
     category,
     lang,
     createdBy,
@@ -474,9 +569,9 @@ export function registerCustomTool(rootDir, def) {
       : {}),
     scope: isGlobal ? "global" : "workspace",
     // Affinity metadata (persisted for future skill/agent matching)
-    ...(skills.length > 0 ? { skills } : {}),
-    ...(agents.length > 0 ? { agents } : {}),
-    ...(templates.length > 0 ? { templates } : {}),
+    ...(normalizedSkills.length > 0 ? { skills: normalizedSkills } : {}),
+    ...(normalizedAgents.length > 0 ? { agents: normalizedAgents } : {}),
+    ...(normalizedTemplates.length > 0 ? { templates: normalizedTemplates } : {}),
     ...(autoInject ? { autoInject } : {}),
     ...(version ? { version } : {}),
   };
@@ -518,6 +613,10 @@ export async function invokeCustomTool(rootDir, toolId, args = [], opts = {}) {
     throw new Error(`invokeCustomTool: tool "${toolId}" not found`);
   }
 
+  const cliArgs = Array.isArray(args)
+    ? args.map((arg) => String(arg))
+    : [String(args)];
+
   const { entry } = result;
   let sPath;
   if (entry.scope === "builtin") {
@@ -536,15 +635,15 @@ export async function invokeCustomTool(rootDir, toolId, args = [], opts = {}) {
   switch (entry.lang) {
     case "mjs":
       cmd = process.execPath; // use same node binary
-      cmdArgs = [sPath, ...args];
+      cmdArgs = [sPath, ...cliArgs];
       break;
     case "sh":
       cmd = process.platform === "win32" ? "bash" : "/bin/sh";
-      cmdArgs = [sPath, ...args];
+      cmdArgs = [sPath, ...cliArgs];
       break;
     case "py":
-      cmd = "python3";
-      cmdArgs = [sPath, ...args];
+      cmd = process.platform === "win32" ? "python" : "python3";
+      cmdArgs = [sPath, ...cliArgs];
       break;
     default:
       throw new Error(`invokeCustomTool: unsupported lang "${entry.lang}"`);
@@ -601,10 +700,13 @@ export async function invokeCustomTool(rootDir, toolId, args = [], opts = {}) {
  * @returns {Promise<void>}
  */
 export async function recordToolUsage(rootDir, toolId) {
+  const normalizedToolId = normalizeToolId(toolId);
+  if (!normalizedToolId) return;
+
   for (const isGlobal of [false, true]) {
     const storeDir = getToolStore(rootDir, { global: isGlobal });
     const index = safeReadIndex(storeDir);
-    const idx = index.findIndex((e) => e.id === toolId);
+    const idx = index.findIndex((e) => e.id === normalizedToolId);
     if (idx < 0) continue;
     index[idx].usageCount = (index[idx].usageCount ?? 0) + 1;
     index[idx].lastUsed = nowISO();
@@ -622,9 +724,12 @@ export async function recordToolUsage(rootDir, toolId) {
  * @returns {boolean} true if the tool was found and removed
  */
 export function deleteCustomTool(rootDir, toolId, { global: isGlobal = false } = {}) {
+  const normalizedToolId = normalizeToolId(toolId);
+  if (!normalizedToolId) return false;
+
   const storeDir = getToolStore(rootDir, { global: isGlobal });
   const index = safeReadIndex(storeDir);
-  const idx = index.findIndex((e) => e.id === toolId);
+  const idx = index.findIndex((e) => e.id === normalizedToolId);
   if (idx < 0) return false;
 
   const entry = index[idx];
@@ -651,9 +756,14 @@ export function deleteCustomTool(rootDir, toolId, { global: isGlobal = false } =
  * @returns {Promise<CustomToolEntry>} the entry as it now exists in global scope
  */
 export async function promoteToGlobal(rootDir, toolId) {
+  const normalizedToolId = normalizeToolId(toolId);
+  if (!normalizedToolId) {
+    throw new Error(`promoteToGlobal: workspace tool "${toolId}" not found`);
+  }
+
   const wsStore = getToolStore(rootDir, { global: false });
   const wsIndex = safeReadIndex(wsStore);
-  const wsEntry = wsIndex.find((e) => e.id === toolId);
+  const wsEntry = wsIndex.find((e) => e.id === normalizedToolId);
   if (!wsEntry) {
     throw new Error(
       `promoteToGlobal: workspace tool "${toolId}" not found`,
@@ -676,7 +786,7 @@ export async function promoteToGlobal(rootDir, toolId) {
 
   // Upsert in global index
   const globalEntry = { ...wsEntry, scope: "global", updatedAt: nowISO() };
-  const existingIdx = globalIndex.findIndex((e) => e.id === toolId);
+  const existingIdx = globalIndex.findIndex((e) => e.id === normalizedToolId);
   if (existingIdx >= 0) {
     globalIndex[existingIdx] = globalEntry;
   } else {
@@ -722,6 +832,8 @@ export function getToolsPromptBlock(rootDir, opts = {}) {
       template,
       limit,
       includeBuiltins,
+      category,
+      tags,
     });
     const affinityIds = new Set(affinityTools.map((t) => t.id));
     const remaining = listCustomTools(rootDir, { category, tags, includeBuiltins })

package/agent/agent-endpoint.mjs

@@ -201,8 +201,7 @@ function isLikelyBosunCommandLine(commandLine) {
     normalized.includes("/bosun/") &&
     (normalized.includes("monitor.mjs") ||
       normalized.includes("cli.mjs") ||
-      normalized.includes("agent-endpoint.mjs") ||
-      normalized.includes("ve-orchestrator"))
+      normalized.includes("agent-endpoint.mjs"))
   ) {
     return true;
   }

package/agent/agent-event-bus.mjs

@@ -18,6 +18,12 @@
  *   createAgentEventBus(options) → AgentEventBus instance
  *   AgentEventBus class
  *   AGENT_EVENT  — Frozen enum of all event types
+ *
+ * Canonical architecture note:
+ * This bus is the canonical runtime ingress for live agent events into the
+ * observability spine. Surfaces may subscribe or rebroadcast, but canonical
+ * event normalization and harness telemetry recording must remain centralized
+ * here plus `infra/session-telemetry.mjs`.
  */
 
 import {
@@ -26,6 +32,12 @@ import {
   snapshotRetryQueue,
 } from "./retry-queue.mjs";
 import { addSpanEvent, recordAgentError, recordIntervention } from "../infra/tracing.mjs";
+import {
+  getHarnessTelemetrySummary,
+  listHarnessTelemetryEvents,
+  recordHarnessTelemetryEvent,
+} from "../infra/session-telemetry.mjs";
+import { normalizeCanonicalBusEvent } from "../infra/event-schema.mjs";
 
 const TAG = "[agent-event-bus]";
 
@@ -147,6 +159,7 @@ export class AgentEventBus {
         : (typeof globalThis.__bosun_setRetryQueueData === "function"
             ? globalThis.__bosun_setRetryQueueData
             : null);
+    this._configDir = options.configDir || process.cwd();
 
     /** @type {Array<{type: string, taskId: string, payload: object, ts: number}>} ring buffer */
     this._eventLog = [];
@@ -259,6 +272,7 @@ export class AgentEventBus {
     if (this._eventLog.length > this._maxEventLogSize) {
       this._eventLog.shift();
     }
+    this._recordCanonicalEvent(event);
 
     // ── WS broadcast
     if (!opts.skipBroadcast) {
@@ -589,6 +603,7 @@ export class AgentEventBus {
    */
   getStatus() {
     const retryQueue = snapshotRetryQueue(this._retryQueueState);
+    const observability = getHarnessTelemetrySummary({ configDir: this._configDir });
     return {
       started: this._started,
       eventLogSize: this._eventLog.length,
@@ -599,6 +614,10 @@ export class AgentEventBus {
       retryQueue,
       liveness: this.getAgentLiveness(),
       errorPatterns: this.getErrorPatternSummary(),
+      observability: {
+        eventCount: Number(observability?.eventCount || 0),
+        lastEventAt: observability?.lastEventAt || null,
+      },
     };
   }
 
@@ -606,6 +625,13 @@ export class AgentEventBus {
     return snapshotRetryQueue(this._retryQueueState);
   }
 
+  getCanonicalEventLog(filter = {}) {
+    return listHarnessTelemetryEvents({
+      ...filter,
+      source: filter.source || "agent-event-bus",
+    }, { configDir: this._configDir });
+  }
+
   clearRetryQueueTask(taskId, reason = "manual") {
     const id = String(taskId || "").trim();
     if (!id) return;
@@ -637,6 +663,13 @@ export class AgentEventBus {
     }
   }
 
+  _recordCanonicalEvent(event) {
+    recordHarnessTelemetryEvent(
+      normalizeCanonicalBusEvent(event),
+      { configDir: this._configDir },
+    );
+  }
+
   _updateRetryQueue(action, meta = {}) {
     this._retryQueueState = reduceRetryQueue(this._retryQueueState, action);
     const snapshot = snapshotRetryQueue(this._retryQueueState);
@@ -1100,5 +1133,3 @@ export class AgentEventBus {
 export function createAgentEventBus(options) {
   return new AgentEventBus(options);
 }
-
-

package/agent/agent-hooks.mjs

@@ -643,7 +643,7 @@ export function registerBuiltinHooks(options = {}) {
 
   // ── PrePush: agent preflight quality gate ──
   if (!skipPrePush) {
-    const preflightScript = "node preflight.mjs";
+    const preflightScript = "node infra/preflight.mjs";
 
     registerHook("PrePush", {
       id: "builtin-prepush-preflight",