bosun 0.40.7 → 0.40.9

package/README.md

@@ -144,17 +144,47 @@ Key places to start:
 
 Bosun enforces a strict quality pipeline in both local hooks and CI:
 
-- **Pre-commit hooks** auto-format and lint staged files.
+- **Pre-commit hooks** run syntax checks and warn when staged source files are missing `CLAUDE:SUMMARY` annotations.
 - **Pre-push hooks** run targeted checks based on changed files (Go, portal, docs).
 - **Demo load smoke test** runs in `npm test` and blocks push if `site/index.html` or `site/ui/demo.html` fails to load required assets.
 - **Prepublish checks** validate package contents and release readiness.
 
+### Codebase annotation audit
+
+Use `bosun audit` to generate and validate repo-level annotations that help future agents navigate the codebase without extra runtime context:
+
+```bash
+# Coverage report for supported source files
+bosun audit scan
+
+# Add missing file summaries and risky-function warnings
+bosun audit generate
+bosun audit warn
+
+# Rebuild lean manifests and the file responsibility index
+bosun audit manifest
+bosun audit index
+bosun audit trim
+
+# CI-safe conformity gate
+bosun audit --ci
+```
+
+Notes:
+
+- `bosun audit --ci` exits non-zero on missing summaries, stale warnings, stale `INDEX.map` entries, or credential-like secrets.
+- `.githooks/pre-commit` already warns on newly staged files that are missing `CLAUDE:SUMMARY`.
+- GitHub Actions can opt into the audit gate by setting the repository variable `BOSUN_AUDIT_CI=1`.
+
 Local commands you can run any time:
 
 ```bash
 # Syntax + tests for bosun package
 npm test
 
+# Annotation conformity gate
+npm run audit:ci
+
 # Prepublish safety checks
 npm run prepublishOnly
 

package/agent/agent-endpoint.mjs

@@ -358,7 +358,11 @@ export class AgentEndpoint {
    */
   async _killProcessOnPort(port) {
     try {
-      const { execSync, spawnSync } = await import("node:child_process");
+      const { spawnSync } = await import("node:child_process");
+      const portNumber = Number.parseInt(String(port), 10);
+      if (!Number.isInteger(portNumber) || portNumber <= 0 || portNumber > 65535) {
+        throw new Error(`invalid port: ${port}`);
+      }
       const isWindows = process.platform === "win32";
       let output;
       const pids = new Set();
@@ -402,12 +406,29 @@ export class AgentEndpoint {
       };
 
       if (isWindows) {
-        // Windows: netstat -ano | findstr
-        output = execSync(`netstat -ano | findstr ":${port}"`, {
+        // Windows: netstat -ano then filter in-process to avoid shell command injection.
+        const netstatRes = spawnSync("netstat", ["-ano"], {
           encoding: "utf8",
           timeout: 5000,
-        }).trim();
-        const lines = output.split("\n").filter((line) => line.includes("LISTENING"));
+          windowsHide: true,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (netstatRes.error) throw netstatRes.error;
+        if (netstatRes.status !== 0) {
+          throw new Error(
+            String(
+              netstatRes.stderr ||
+              netstatRes.stdout ||
+              `netstat exited with status ${netstatRes.status}`,
+            ).trim(),
+          );
+        }
+        output = String(netstatRes.stdout || "").trim();
+        const lines = output
+          .split("\n")
+          .filter(
+            (line) => line.includes("LISTENING") && line.includes(`:${portNumber}`),
+          );
         for (const line of lines) {
           const parts = line.trim().split(/\s+/);
           const pid = parts[parts.length - 1];
@@ -417,29 +438,37 @@ export class AgentEndpoint {
         }
       } else {
         // Linux/macOS: lsof -i
-        try {
-          output = execSync(`lsof -ti :${port}`, {
-            encoding: "utf8",
-            timeout: 5000,
-          }).trim();
-          const pidList = output.split("\n").filter((pid) => pid.trim());
-          for (const pid of pidList) {
-            if (pid && /^\d+$/.test(pid) && !protectedPids.has(pid)) {
-              pids.add(pid);
-            }
-          }
-          if (pidList.length > 0 && pids.size === 0) {
-            console.log(
-              `${TAG} Port ${port} held by own process tree (PIDs: ${pidList.join(", ")}) — skipping kill`,
-            );
-            return;
-          }
-        } catch (lsofErr) {
-          // lsof returns exit code 1 when no processes found (port is free)
-          if (lsofErr.status === 1) {
-            return; // Port is already free
+        const lsofRes = spawnSync("lsof", ["-ti", `:${portNumber}`], {
+          encoding: "utf8",
+          timeout: 5000,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (lsofRes.error) throw lsofRes.error;
+        // lsof returns exit code 1 when no processes found (port is free)
+        if (lsofRes.status === 1) {
+          return;
+        }
+        if (lsofRes.status !== 0) {
+          throw new Error(
+            String(
+              lsofRes.stderr ||
+              lsofRes.stdout ||
+              `lsof exited with status ${lsofRes.status}`,
+            ).trim(),
+          );
+        }
+        output = String(lsofRes.stdout || "").trim();
+        const pidList = output.split("\n").filter((pid) => pid.trim());
+        for (const pid of pidList) {
+          if (pid && /^\d+$/.test(pid) && !protectedPids.has(pid)) {
+            pids.add(pid);
           }
-          throw lsofErr;
+        }
+        if (pidList.length > 0 && pids.size === 0) {
+          console.log(
+            `${TAG} Port ${portNumber} held by own process tree (PIDs: ${pidList.join(", ")}) — skipping kill`,
+          );
+          return;
         }
       }
 
@@ -490,10 +519,7 @@ export class AgentEndpoint {
             }
           } else {
             // Graceful SIGTERM first — only escalate to SIGKILL if still alive
-            execSync(`kill ${pid}`, {
-              encoding: "utf8",
-              timeout: 5000,
-            });
+            process.kill(Number(pid), "SIGTERM");
           }
         } catch (killErr) {
           /* may already be dead — log for diagnostics */
@@ -528,7 +554,7 @@ export class AgentEndpoint {
           try {
             process.kill(Number(pid), 0); // probe — throws if dead
             console.warn(`${TAG} PID ${pid} still alive after SIGTERM — sending SIGKILL`);
-            execSync(`kill -9 ${pid}`, { encoding: "utf8", timeout: 5000 });
+            process.kill(Number(pid), "SIGKILL");
           } catch {
             /* already dead — good */
           }

package/agent/agent-pool.mjs

@@ -682,7 +682,15 @@ async function withTemporaryEnv(overrides, fn) {
 function buildCodexSdkOptions(envInput = process.env) {
   const { env: resolvedEnv } = resolveCodexProfileRuntime(envInput);
   const baseUrl = resolvedEnv.OPENAI_BASE_URL || "";
-  const isAzure = baseUrl.includes(".openai.azure.com");
+  const isAzure = (() => {
+        try {
+          const parsed = new URL(baseUrl);
+          const host = String(parsed.hostname || "").toLowerCase();
+          return host === "openai.azure.com" || host.endsWith(".openai.azure.com");
+        } catch {
+          return false;
+        }
+      })();
   const env = { ...resolvedEnv };
   // Always strip OPENAI_BASE_URL — for Azure we use config overrides,
   // for non-Azure the CLI should use its built-in endpoint.

package/agent/autofix.mjs

@@ -536,7 +536,15 @@ export function runCodexExec(
       // Otherwise strip OPENAI_BASE_URL so the CLI uses its ChatGPT OAuth.
       const { env: codexEnv } = resolveCodexProfileRuntime(process.env);
       const baseUrl = codexEnv.OPENAI_BASE_URL || "";
-      const isAzure = baseUrl.includes(".openai.azure.com");
+      const isAzure = (() => {
+        try {
+          const parsed = new URL(baseUrl);
+          const host = String(parsed.hostname || "").toLowerCase();
+          return host === "openai.azure.com" || host.endsWith(".openai.azure.com");
+        } catch {
+          return false;
+        }
+      })();
       if (isAzure) {
         // Map OPENAI_API_KEY → AZURE_OPENAI_API_KEY for Azure auth header
         if (codexEnv.OPENAI_API_KEY && !codexEnv.AZURE_OPENAI_API_KEY) {
@@ -568,22 +576,11 @@ export function runCodexExec(
         // Node double-killing the child with SIGTERM before our handler runs.
         env: codexEnv,
       };
-      if (process.platform === "win32") {
-        // On Windows, spawn with shell: true so cmd.exe can resolve .cmd/.ps1
-        // shims (e.g. codex.cmd installed by npm). Without shell: true, Node's
-        // spawn() looks for a literal "codex" executable which doesn't exist
-        // on Windows — only codex.cmd does — causing ENOENT (os error 2).
-        // Arguments are passed as an array so shell word-splitting is safe.
-        child = spawn("codex", args, {
-          ...spawnOptions,
-          shell: true,
-        });
-      } else {
-        child = spawn("codex", args, {
-          ...spawnOptions,
-          shell: false,
-        });
-      }
+      const codexBin = process.platform === "win32" ? "codex.cmd" : "codex";
+      child = spawn(codexBin, args, {
+        ...spawnOptions,
+        shell: false,
+      });
     } catch (err) {
       return promiseResolve({
         success: false,

package/agent/bosun-skills.mjs

@@ -23,6 +23,10 @@ import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+function readBuiltinSkillFile(filename) {
+  return readFileSync(resolve(__dirname, "skills", filename), "utf8");
+}
+
 // ── Analytics stream path (same file task-executor writes to) ────────────────
 const _SKILL_STREAM_PATH = resolve(
   __dirname,
@@ -765,7 +769,7 @@ await engine.process(data);
 `,
   },
   {
-    filename: "codebase-annotation-audit.md",
+    filename: "skill-codebase-audit.md",
     title: "Codebase Annotation Audit",
     tags: [
       "audit", "annotation", "documentation", "summary", "inventory",
@@ -773,117 +777,7 @@ await engine.process(data);
       "manifest", "conformity", "regeneration", "claude", "copilot",
     ],
     scope: "global",
-    content: `# Skill: Codebase Annotation Audit
-
-## Purpose
-Systematically audit and annotate a codebase so that *future* AI agents can
-navigate it 4× faster, use 20% fewer tokens, and avoid false-positive changes.
-This skill is **documentation-only** — it MUST NOT fix bugs, refactor code,
-or change program behavior.
-
-## Philosophy — LEAN Annotations
-
-Modern AI coding SDKs (Copilot, Codex, Claude Code) already auto-compact
-context. Adding a memory/compaction layer on top is wasteful. What *does* help
-is **repo-level documentation** that agents read at the start of a session:
-summaries, warnings, architectural notes, and module manifests. These cost zero
-runtime tokens and dramatically reduce exploration time.
-
-## Annotation Format
-
-Use structured comment headers that agents are trained to recognize:
-
-\\\`\\\`\\\`
-// BOSUN:SUMMARY — <module-name>
-// <1–3 sentence summary of purpose, key types, and public API>
-\\\`\\\`\\\`
-
-\\\`\\\`\\\`
-// BOSUN:WARN — <module-name>
-// <non-obvious pitfall, race condition, or constraint agents MUST know>
-\\\`\\\`\\\`
-
-- Place annotations at the **top of the file**, after imports / shebang.
-- Keep each annotation to ≤ 3 lines.
-- Do NOT annotate trivial files (configs, lockfiles, generated code).
-
-## 6-Phase Audit Process
-
-### Phase 1 — Inventory
-Enumerate every source file.  For each file record:
-| Field | Value |
-|-------|-------|
-| path | relative from repo root |
-| lang | file extension / language |
-| lines | line count |
-| has_summary | yes / no |
-| has_warn | yes / no |
-| category | core / util / test / config / generated |
-
-Output: \\\`.bosun/audit/inventory.json\\\`
-
-### Phase 2 — Summaries
-For every file where \\\`has_summary === false\\\` and \\\`category !== "generated"\\\`:
-1. Read the file.
-2. Write a \\\`BOSUN:SUMMARY\\\` comment at the top.
-3. Stage the file.
-
-### Phase 3 — Warnings
-For every file, check for non-obvious constraints:
-- Singleton/caching requirements (must be module-scope)
-- Async fire-and-forget patterns (unhandled rejections)
-- Order-dependent initialization
-- Platform-specific behavior (Windows paths, etc.)
-
-Add \\\`BOSUN:WARN\\\` comments where found.
-
-### Phase 4 — Manifest Audit
-Ensure \\\`AGENTS.md\\\` (or equivalent) at repo root is accurate:
-- Lists all top-level modules with 1-line descriptions.
-- Documents build / test / lint commands.
-- Documents environment variables.
-- Documents commit conventions.
-- Lists known constraints or gotchas.
-
-If the file is outdated or missing sections, append corrections.
-
-### Phase 5 — Conformity Check
-Re-scan all annotations and validate:
-- \\\`BOSUN:SUMMARY\\\` is present in every non-trivial source file.
-- \\\`BOSUN:WARN\\\` exists for files with known pitfalls.
-- No stale annotations reference symbols/functions that no longer exist.
-
-Output: \\\`.bosun/audit/conformity-report.json\\\`
-
-### Phase 6 — Regeneration Schedule
-Annotations rot. Add a \\\`.bosun/audit/schedule.json\\\` with:
-\\\`\\\`\\\`json
-{
-  "lastFullAudit": "<ISO timestamp>",
-  "nextRecommendedAudit": "<ISO timestamp + 30 days>",
-  "filesAudited": <count>,
-  "summariesAdded": <count>,
-  "warningsAdded": <count>,
-  "conformityScore": <0-100>
-}
-\\\`\\\`\\\`
-
-## Hard Rules
-
-1. **Do NOT change program behavior.** Only add/update comments and documentation.
-2. **Do NOT refactor, fix bugs, or rename symbols.** Documentation only.
-3. **Do NOT annotate generated files** (lockfiles, build output, .min.js, etc.).
-4. **Keep summaries ≤ 3 lines.** Agents need density, not essays.
-5. **Keep warnings actionable.** "This is complex" is useless.
-   "Must call init() before query() — throws otherwise" is helpful.
-6. **Stage files individually** — never \\\`git add .\\\`.
-7. **Commit with** \\\`docs(audit): annotate <module>\\\` — not feat/fix.
-
-## Success Metrics
-- A/B tested: annotated repos show 4× faster agent navigation.
-- 20% fewer tokens consumed per task.
-- Zero false-positive code changes from confused agents.
-`,
+    content: readBuiltinSkillFile("skill-codebase-audit.md"),
   },
   {
     filename: "custom-tool-creation.md",
@@ -1298,3 +1192,4 @@ export function buildRelevantSkillsPromptBlock(bosunHome, taskTitle, taskDescrip
 
   return lines.join("\n").trim();
 }
+

package/agent/skills/skill-codebase-audit.md

@@ -0,0 +1,111 @@
+# Skill: Codebase Annotation Audit
+
+## Purpose
+Systematically audit and annotate a codebase so that *future* AI agents can
+navigate it 4× faster, use 20% fewer tokens, and avoid false-positive changes.
+This skill is **documentation-only** — it MUST NOT fix bugs, refactor code,
+or change program behavior.
+
+## Philosophy — LEAN Annotations
+
+Modern AI coding SDKs (Copilot, Codex, Claude Code) already auto-compact
+context. Adding a memory/compaction layer on top is wasteful. What *does* help
+is **repo-level documentation** that agents read at the start of a session:
+summaries, warnings, architectural notes, and module manifests. These cost zero
+runtime tokens and dramatically reduce exploration time.
+
+## Annotation Format
+
+Use structured comment headers that agents are trained to recognize:
+
+```
+// CLAUDE:SUMMARY — <module-name>
+// <1–3 sentence summary of purpose, key types, and public API>
+```
+
+```
+// CLAUDE:WARN — <module-name>
+// <non-obvious pitfall, race condition, or constraint agents MUST know>
+```
+
+- Place annotations at the **top of the file**, after imports / shebang.
+- Keep each annotation to ≤ 3 lines.
+- Do NOT annotate trivial files (configs, lockfiles, generated code).
+
+## 6-Phase Audit
+
+### Phase 1 — Inventory
+Enumerate every source file. For each file record:
+| Field | Value |
+|-------|-------|
+| path | relative from repo root |
+| lang | file extension / language |
+| lines | line count |
+| has_summary | yes / no |
+| has_warn | yes / no |
+| category | core / util / test / config / generated |
+
+Output: `.bosun/audit/inventory.json`
+
+### Phase 2 — Summaries
+For every file where `has_summary === false` and `category !== "generated"`:
+1. Read the file.
+2. Write a `CLAUDE:SUMMARY` comment at the top.
+3. Stage the file.
+
+### Phase 3 — Warnings
+For every file, check for non-obvious constraints:
+- Singleton/caching requirements (must be module-scope)
+- Async fire-and-forget patterns (unhandled rejections)
+- Order-dependent initialization
+- Platform-specific behavior (Windows paths, etc.)
+
+Add `CLAUDE:WARN` comments where found.
+
+### Phase 4 — Manifest Audit
+Ensure `AGENTS.md` (or equivalent) at repo root is accurate:
+- Lists all top-level modules with 1-line descriptions.
+- Documents build / test / lint commands.
+- Documents environment variables.
+- Documents commit conventions.
+- Lists known constraints or gotchas.
+
+If the file is outdated or missing sections, append corrections.
+
+### Phase 5 — Conformity Check
+Re-scan all annotations and validate:
+- `CLAUDE:SUMMARY` is present in every non-trivial source file.
+- `CLAUDE:WARN` exists for files with known pitfalls.
+- No stale annotations reference symbols/functions that no longer exist.
+
+Output: `.bosun/audit/conformity-report.json`
+
+### Phase 6 — Regeneration Schedule
+Annotations rot. Add a `.bosun/audit/schedule.json` with:
+```json
+{
+  "lastFullAudit": "<ISO timestamp>",
+  "nextRecommendedAudit": "<ISO timestamp + 30 days>",
+  "filesAudited": <count>,
+  "summariesAdded": <count>,
+  "warningsAdded": <count>,
+  "conformityScore": <0-100>
+}
+```
+
+## Hard Rules
+
+1. **Do NOT change program behavior.** Only add/update comments and documentation.
+2. **Do NOT refactor, fix bugs, or rename symbols.** Documentation only.
+3. **Do NOT annotate generated files** (lockfiles, build output, `.min.js`, etc.).
+4. **Keep summaries ≤ 3 lines.** Agents need density, not essays.
+5. **Keep warnings actionable.** "This is complex" is useless.
+   "Must call init() before query() — throws otherwise" is helpful.
+6. **Stage files individually** — never `git add .`.
+7. **Commit with** `docs(audit): annotate <module>` — not `feat`/`fix`.
+
+## Success Metrics
+- A/B tested: annotated repos show 4× faster agent navigation.
+- 20% fewer tokens consumed per task.
+- Zero false-positive code changes from confused agents.
+

package/bosun-tui.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * bosun-tui — Terminal User Interface for Bosun
+ *
+ * A terminal-based UI for monitoring Bosun agents, tasks, and workflows.
+ * Built with Ink (React-like CLI framework).
+ *
+ * Usage:
+ *   bosun-tui              # Start the TUI
+ *   bosun-tui --help       # Show help
+ *   bosun-tui --port 3080  # Connect to specific port
+ */
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(new URL(".", import.meta.url)));
+
+function showHelp() {
+  const version = JSON.parse(
+    readFileSync(resolve(__dirname, "package.json"), "utf8"),
+  ).version;
+
+  console.log(`
+  bosun-tui v${version}
+  Terminal User Interface for Bosun
+
+  USAGE
+    bosun-tui [options]
+
+  OPTIONS
+    --port <n>         UI server port to connect (default: 3080 or TELEGRAM_UI_PORT env)
+    --host <host>     UI server host (default: localhost)
+    --connect         Connect to existing UI server (don't start monitor)
+    --screen <name>   Initial screen (tasks|agents|status)
+    --refresh <ms>    Stats refresh interval (default: 2000ms)
+    --help            Show this help
+    --version         Show version
+
+  SCREENS
+    tasks    Kanban board with task CRUD
+    agents   Live agent session table
+    status   System status overview
+
+  KEYBOARD NAVIGATION
+    Tab / Shift+Tab   Navigate between panels
+    ↑↓←→             Navigate within panels
+    Enter            Select / Execute action
+    Esc              Back / Close modal
+    c                Create new task (tasks screen)
+    r                Refresh data
+    q                Quit
+
+  EXAMPLES
+    bosun-tui --port 3080
+    bosun-tui --screen tasks
+    bosun-tui --connect --port 3080
+  `);
+}
+
+function getArgValue(flag, defaultValue = "") {
+  const args = process.argv.slice(2);
+  const match = args.find((arg) => arg.startsWith(`${flag}=`));
+  if (match) {
+    return match.slice(flag.length + 1).trim();
+  }
+  const idx = args.indexOf(flag);
+  if (idx >= 0 && args[idx + 1] && !args[idx + 1].startsWith("--")) {
+    return args[idx + 1].trim();
+  }
+  return defaultValue;
+}
+
+function getArgFlag(flag) {
+  const args = process.argv.slice(2);
+  return args.includes(flag);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (getArgFlag("--help") || args.includes("-h")) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (getArgFlag("--version") || args.includes("-v")) {
+    const version = JSON.parse(
+      readFileSync(resolve(__dirname, "package.json"), "utf8"),
+    ).version;
+    console.log(`bosun-tui v${version}`);
+    process.exit(0);
+  }
+
+  const port = Number(getArgValue("--port", process.env.TELEGRAM_UI_PORT || "3080")) || 3080;
+  const host = getArgValue("--host", "localhost");
+  const connectOnly = getArgFlag("--connect");
+  const initialScreen = getArgValue("--screen", "status");
+  const refreshMs = Number(getArgValue("--refresh", "2000")) || 2000;
+
+  console.log(`[bosun-tui] Starting...`);
+  console.log(`[bosun-tui] Connecting to ${host}:${port}`);
+
+  try {
+    const { render } = await import("ink");
+    const importErrors = [];
+
+    let App;
+    try {
+      const appModule = await import("./tui/app.mjs");
+      App = appModule.default;
+    } catch (importErr) {
+      importErrors.push(`App: ${importErr.message}`);
+      console.error(`[bosun-tui] Failed to import TUI app: ${importErr.message}`);
+      console.log(`[bosun-tui] TUI requires ink. Install with: npm install ink`);
+      process.exit(1);
+    }
+
+    const { waitUntilExit } = await import("ink");
+
+    const app = render(
+      App({
+        host,
+        port,
+        connectOnly,
+        initialScreen,
+        refreshMs,
+      }),
+    );
+
+    process.exitCode = await waitUntilExit(app);
+  } catch (err) {
+    console.error(`[bosun-tui] Failed to start: ${err.message}`);
+    console.log(`[bosun-tui] Ensure bosun is running or use --connect to connect to an existing UI server`);
+    process.exit(1);
+  }
+}
+
+main();