release: v0.4.2 — background daemon, env autoload, cwd-agnostic config, Linear pickup fixes (#50)

* feat: detach openswarm start into a background daemon

- `openswarm start` now spawns a detached child and returns immediately
- adds `openswarm stop` (SIGTERM + PID cleanup) and `openswarm status`
- logs stream to ~/.config/openswarm/logs/openswarm.log
- PID file at ~/.config/openswarm/openswarm.pid, with stale-file recovery
- `--foreground` / `-F` preserves the previous attached behavior for debugging
- bump to 0.4.2

* feat: bundle @intrect/cxt and expose it to spawned workers

- add @intrect/cxt ^0.1.0 as a runtime dependency
- inject OpenSwarm's own node_modules/.bin into PATH for every worker/planner
  CLI spawn via new buildWorkerEnv helper
- user's shell PATH and ~/.claude/* are untouched — cxt is only visible to
  processes OpenSwarm itself starts
- worker prompt templates (en/ko) now list cxt as an available tool so agents
  know they can run it for entity lookup, FTS search, and bad-smell scans

* feat: auto-load .env so the daemon picks up LINEAR_API_KEY/LINEAR_TEAM_ID

Before: `openswarm start` run from a non-interactive shell without the Linear
(or Discord) vars exported silently fell through config validation with
"Linear credentials not set — disabling Linear integration", so no issues
were ever picked up even though the keys sat in .env.

Now index.ts loads the first .env it finds (\$OPENSWARM_ENV → dir of
\$OPENSWARM_CONFIG → cwd → ~/.config/openswarm → ~/.openswarm), without
overwriting values already present in process.env. A shell export still wins.

Verified: daemon now logs `[Linear] Fetching issues for all:false` →
`[HB] ✓ Found 100 tasks from Linear`, vs the previous
`⏭ Linear not configured — skipping`.

* fix: pick up Linear issues across all configured teams + projects

Heartbeat was missing analogModeling issues even with the project enabled,
because the fetch + filter pipeline silently dropped them at three points:

- enabledProjects matched paths byte-equal, so macOS/Windows case-insensitive
  filesystems treated AnalogModeling and analogModeling as different entries.
  Fixed in autonomousRunner.isProjectEnabled.
- linear.getMyIssues issued a single { team: { in: [...] } } query capped at
  first: 50 — one busy team monopolized the page and starved smaller teams.
  Switched to an adaptive fetch: one wide query first, fall back to per-team
  fan-out only when the first page saturates. PER_TEAM cap raised from 50
  to 100.
- core/service.ts heartbeat fetcher was using full mode (3 resolver calls
  per issue: project + comments + labels). At ~200 issues × 4 HB/hour that
  was tripping Linear's 3500 req/hr ceiling. Switched to slim mode (1 call
  per issue, project only). Comment-based task-state hydration is sacrificed
  on this path.
- taskState.getTaskReadiness only reactivated decomposed tasks if Linear
  state was Todo or In Progress. In Review now counts as actionable too,
  so reviewer feedback on a decomposed task gets picked up rather than
  ignored.

Author: unohee

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@intrect/openswarm",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Autonomous AI agent orchestrator — Claude, GPT, Codex, and local models (Ollama/LMStudio/llama.cpp)",
   "license": "GPL-3.0",
   "type": "module",
@@ -43,6 +43,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.72.1",
+    "@intrect/cxt": "^0.1.0",
     "@intrect/openswarm": "^0.2.1",
     "@lancedb/lancedb": "^0.23.0",
     "@linear/sdk": "^19.0.0",

package.json

@@ -8,6 +8,7 @@ import fs from 'node:fs/promises';
 import type { CliAdapter, CliRunOptions, CliRunResult } from './types.js';
 import { parseCliStreamChunk } from '../agents/cliStreamParser.js';
 import { registerProcess } from './processRegistry.js';
+import { buildWorkerEnv } from './envPath.js';
 
 /**
  * Spawn a CLI process using the given adapter and options.
@@ -40,7 +41,10 @@ export async function spawnCli(
       const proc = spawn(cmd, {
         shell: true,
         cwd: options.cwd,
-        env: process.env,
+        // Inject OpenSwarm's bundled node_modules/.bin (gives workers access
+        // to `cxt` and other shipped CLIs) without touching the user's shell
+        // PATH or ~/.claude/ config.
+        env: buildWorkerEnv(process.env),
         stdio: ['ignore', 'pipe', 'pipe'],
       });
 

src/adapters/base.ts

@@ -0,0 +1,52 @@
+// ============================================
+// OpenSwarm - Worker environment PATH helper
+// ============================================
+//
+// Workers spawned by OpenSwarm need access to bundled CLI dependencies
+// (notably `cxt` from @intrect/cxt) without the user having them installed
+// globally. We inject OpenSwarm's own `node_modules/.bin` into PATH for the
+// spawned process only — user's shell PATH and ~/.claude/* are untouched.
+
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { delimiter } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Resolve OpenSwarm's bundled `node_modules/.bin` directory.
+ *
+ * envPath.js lives at `<pkg>/dist/adapters/envPath.js` after build, so the
+ * package root is two directories up. During `npm run dev` / `tsx`, the file
+ * is at `<pkg>/src/adapters/envPath.ts` — same relative structure.
+ *
+ * Returns null if the .bin directory does not exist (e.g. dev checkout
+ * without `npm install`), so callers can fall back to process.env.PATH as-is.
+ */
+export function getBundledBinDir(): string | null {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = resolve(here, '..', '..');
+  const binDir = join(pkgRoot, 'node_modules', '.bin');
+  return existsSync(binDir) ? binDir : null;
+}
+
+/**
+ * Build an env object for spawned workers with OpenSwarm's bundled `.bin`
+ * directory prepended to PATH. Keeps every other env var untouched.
+ *
+ * Prepending (not appending) means a locally-bundled `cxt` wins over an
+ * older global install, which matters when we start pinning cxt versions.
+ */
+export function buildWorkerEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const binDir = getBundledBinDir();
+  if (binDir === null) return { ...base };
+
+  const existingPath = base.PATH ?? base.Path ?? '';
+  // Avoid duplicate entries if this env is reused across spawns.
+  const parts = existingPath.split(delimiter).filter(Boolean);
+  if (parts[0] === binDir) {
+    return { ...base };
+  }
+  const nextPath = [binDir, ...parts.filter((p) => p !== binDir)].join(delimiter);
+
+  return { ...base, PATH: nextPath };
+}

src/adapters/envPath.ts

@@ -76,13 +76,29 @@ export class AutonomousRunner {
   // Explicitly enabled project paths (allow-list; empty = nothing runs)
   private enabledProjects = new Set<string>();
 
+  /**
+   * macOS (APFS default) and Windows have case-insensitive filesystems by
+   * default, so `/Users/x/dev/AnalogModeling` and `/Users/x/dev/analogModeling`
+   * refer to the same directory. Do the enabled-set comparison in a case-
+   * insensitive way on those platforms so UI-captured casing doesn't
+   * mismatch Linear's project-name casing.
+   */
+  private get pathsCaseInsensitive(): boolean {
+    return process.platform === 'darwin' || process.platform === 'win32';
+  }
+
+  private normalizePath(p: string): string {
+    return this.pathsCaseInsensitive ? p.toLowerCase() : p;
+  }
+
   /** Check if a resolved path is under any enabled project */
   private isProjectEnabled(resolvedPath: string): boolean {
     if (this.enabledProjects.size === 0) return false;
-    if (this.enabledProjects.has(resolvedPath)) return true;
-    // Check if resolvedPath is a subdirectory of any enabled project
+    const needle = this.normalizePath(resolvedPath);
     for (const enabled of this.enabledProjects) {
-      if (resolvedPath.startsWith(enabled + '/')) return true;
+      const hay = this.normalizePath(enabled);
+      if (hay === needle) return true;
+      if (needle.startsWith(hay + '/')) return true;
     }
     return false;
   }

src/automation/autonomousRunner.ts

@@ -166,10 +166,72 @@ program
 
 program
   .command('start')
-  .description('Start the full daemon (requires config.yaml with Discord + Linear)')
+  .description('Start the full daemon in the background (use --foreground to stay attached)')
+  .option('-F, --foreground', 'Run in the foreground instead of detaching (for debugging / LaunchAgent)')
+  .action(async (opts: { foreground?: boolean }) => {
+    if (opts.foreground) {
+      // Dynamic import triggers the top-level main() in index.ts
+      await import('./index.js');
+      return;
+    }
+
+    const { startDaemon } = await import('./cli/daemon.js');
+    try {
+      const { pid, logFile } = startDaemon();
+      console.log(`OpenSwarm started in background (pid ${pid}).`);
+      console.log(`  logs:    ${logFile}`);
+      console.log(`  stop:    openswarm stop`);
+      console.log(`  status:  openswarm status`);
+    } catch (err) {
+      console.error(`Failed to start: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+// openswarm stop
+
+program
+  .command('stop')
+  .description('Stop the background daemon (sends SIGTERM)')
+  .option('-t, --timeout <ms>', 'Max time to wait for graceful shutdown (default 10000)', '10000')
+  .action(async (opts: { timeout: string }) => {
+    const timeoutMs = parseInt(opts.timeout, 10);
+    const { stopDaemon } = await import('./cli/daemon.js');
+    try {
+      const stopped = await stopDaemon(Number.isFinite(timeoutMs) ? timeoutMs : 10_000);
+      if (!stopped) {
+        console.log('OpenSwarm is not running.');
+        return;
+      }
+      console.log('OpenSwarm stopped.');
+    } catch (err) {
+      console.error(`Failed to stop: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+// openswarm status
+
+program
+  .command('status')
+  .description('Report daemon status (pid, uptime, log path)')
   .action(async () => {
-    // Dynamic import triggers the top-level main() in index.ts
-    await import('./index.js');
+    const { getDaemonStatus } = await import('./cli/daemon.js');
+    const status = getDaemonStatus();
+    if (!status.running) {
+      console.log('OpenSwarm is not running.');
+      console.log(`  pid file: ${status.pidFile}`);
+      console.log(`  log file: ${status.logFile}`);
+      return;
+    }
+    const uptime = status.uptimeSeconds ?? 0;
+    const h = Math.floor(uptime / 3600);
+    const m = Math.floor((uptime % 3600) / 60);
+    const s = uptime % 60;
+    console.log(`OpenSwarm is running.`);
+    console.log(`  pid:    ${status.pid}`);
+    console.log(`  uptime: ${h}h ${m}m ${s}s`);
+    console.log(`  logs:   ${status.logFile}`);
   });
 
 // openswarm dash