agentxchain 0.4.0 → 0.4.2

package/README.md

@@ -19,35 +19,70 @@ npx agentxchain init
 ```bash
 agentxchain init                      # create a project (template selection)
 cd my-project/
-export CURSOR_API_KEY=your_key        # from cursor.com/settings
+echo "CURSOR_API_KEY=your_key" >> .env # from cursor.com/settings -> Cloud Agents
 agentxchain start --ide cursor        # launch agents
 agentxchain watch                     # coordinate turns automatically
 ```
 
+> `CURSOR_API_KEY` is required for Cursor commands (`start/watch/stop/claim/release` when using Cursor sessions).
+
 ## Commands
 
 | Command | What it does |
 |---------|-------------|
 | `init` | Create project folder with agents, protocol files, and templates |
-| `start` | Launch agents in Cursor, Claude Code, or VS Code |
+| `start` | Launch agents in Cursor, Claude Code, or VS Code (`CURSOR_API_KEY` required for Cursor) |
 | `watch` | The referee — coordinates turns, enforces TTL, wakes agents |
 | `status` | Show lock, phase, agents, Cursor session info |
 | `claim` | Human takes control (pauses Cursor agents) |
 | `release` | Hand lock back to agents |
 | `stop` | Terminate all running agents |
+| `branch` | Show/set Cursor branch override (`cursor.ref`) |
 | `config` | View/edit config, add/remove agents, change rules |
 | `update` | Self-update CLI from npm |
 
+### Branch selection
+
+By default, Cursor launches use your current local git branch. You can override this when needed.
+
+```bash
+agentxchain branch                  # show current/effective branch
+agentxchain branch develop          # pin to a specific branch
+agentxchain branch --use-current    # pin to whatever branch you're on now
+agentxchain branch --unset          # remove pin; follow active git branch
+```
+
+### Additional command flags
+
+```bash
+agentxchain watch --daemon          # run watch in background
+agentxchain release --force         # force-release non-human holder lock
+```
+
 ## Key features
 
 - **Claim-based coordination** — no fixed turn order; agents self-organize
 - **User-defined teams** — any number of agents, any roles
 - **Cursor Cloud Agents** — launch and manage agents via API
+- **Branch-safe launching** — defaults to active git branch; optional `branch` override
+- **Project `.env` loading** — CLI auto-reads `CURSOR_API_KEY` from project root `.env`
 - **Lock TTL** — stale locks auto-released after timeout
 - **Verify command** — agents must pass tests before releasing
 - **Human-in-the-loop** — claim/release to intervene anytime
 - **Team templates** — SaaS MVP, Landing Page, Bug Squad, API Builder, Refactor Team
 
+## Publish updates (maintainers)
+
+```bash
+cd cli
+bash scripts/publish-npm.sh              # patch bump + publish
+bash scripts/publish-npm.sh minor        # minor bump + publish
+bash scripts/publish-npm.sh 0.5.0        # explicit version + publish
+bash scripts/publish-npm.sh patch --dry-run
+```
+
+If `NPM_TOKEN` exists in `cli/.env`, the script uses it automatically.
+
 ## Links
 
 - [agentxchain.dev](https://agentxchain.dev)

package/bin/agentxchain.js

@@ -9,13 +9,14 @@ import { configCommand } from '../src/commands/config.js';
 import { updateCommand } from '../src/commands/update.js';
 import { watchCommand } from '../src/commands/watch.js';
 import { claimCommand, releaseCommand } from '../src/commands/claim.js';
+import { branchCommand } from '../src/commands/branch.js';
 
 const program = new Command();
 
 program
   .name('agentxchain')
   .description('Multi-agent coordination in your IDE')
-  .version('0.1.1');
+  .version('0.4.1');
 
 program
   .command('init')
@@ -51,6 +52,13 @@ program
   .option('-j, --json', 'Output config as JSON')
   .action(configCommand);
 
+program
+  .command('branch [name]')
+  .description('Show or set the Cursor branch used for agent launches')
+  .option('--use-current', 'Set override to the current local git branch')
+  .option('--unset', 'Remove override and follow active git branch automatically')
+  .action(branchCommand);
+
 program
   .command('watch')
   .description('Watch lock.json and coordinate agent turns (the referee)')
@@ -66,6 +74,7 @@ program
 program
   .command('release')
   .description('Release the lock (hand back to agents)')
+  .option('--force', 'Force release even if a non-human holder has the lock')
   .action(releaseCommand);
 
 program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
   "scripts": {
     "dev": "node bin/agentxchain.js",
     "build:macos": "bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile=dist/agentxchain-macos-arm64",
-    "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64"
+    "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64",
+    "publish:npm": "bash scripts/publish-npm.sh"
   },
   "keywords": [
     "ai",

package/src/adapters/cursor.js

@@ -2,7 +2,8 @@ import { writeFileSync, readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { generateSeedPrompt } from '../lib/seed-prompt.js';
-import { getRepoUrl } from '../lib/repo.js';
+import { getRepoUrl, getCurrentBranch } from '../lib/repo.js';
+import { getCursorApiKey, printCursorApiKeyRequired } from '../lib/cursor-api-key.js';
 
 const API_BASE = 'https://api.cursor.com/v0';
 
@@ -16,11 +17,11 @@ function authHeaders(apiKey) {
 // --- Public API ---
 
 export async function launchCursorAgents(config, root, opts) {
-  const apiKey = process.env.CURSOR_API_KEY;
+  const apiKey = getCursorApiKey(root);
 
   if (!apiKey) {
-    printApiKeyHelp();
-    return fallbackPromptOutput(config, opts);
+    printCursorApiKeyRequired('`agentxchain start --ide cursor`');
+    return [];
   }
 
   const repoUrl = await getRepoUrl(root);
@@ -32,9 +33,11 @@ export async function launchCursorAgents(config, root, opts) {
   }
 
   const model = config.cursor?.model || 'default';
-  const ref = config.cursor?.ref || 'main';
+  const ref = config.cursor?.ref || getCurrentBranch(root) || 'main';
+  console.log(chalk.dim(`  Cursor source: ${repoUrl} @ ${ref}`));
   const agents = filterAgents(config, opts.agent);
   const launched = [];
+  let branchErrorCount = 0;
 
   for (const [id, agent] of Object.entries(agents)) {
     const prompt = generateSeedPrompt(id, agent, config);
@@ -56,6 +59,9 @@ export async function launchCursorAgents(config, root, opts) {
       if (!res.ok) {
         const errBody = await res.text();
         console.log(chalk.red(`  ✗ ${id}: ${res.status} ${errBody}`));
+        if (errBody.includes('Failed to verify existence of branch')) {
+          branchErrorCount += 1;
+        }
         continue;
       }
 
@@ -76,7 +82,16 @@ export async function launchCursorAgents(config, root, opts) {
   }
 
   if (launched.length > 0) {
-    saveSession(root, launched, repoUrl);
+    saveSession(root, launched, repoUrl, ref);
+  }
+
+  if (launched.length === 0 && branchErrorCount > 0) {
+    console.log('');
+    console.log(chalk.yellow('  Launch failed because the branch ref is invalid for this repository.'));
+    console.log(chalk.dim('  Fix by setting the branch explicitly in agentxchain.json:'));
+    console.log(chalk.bold('  "cursor": { "ref": "your-default-branch" }'));
+    console.log(chalk.dim('  Or switch to the target branch locally, then re-run start.'));
+    console.log('');
   }
 
   return launched;
@@ -137,12 +152,13 @@ export function loadSession(root) {
 
 // --- Internal ---
 
-function saveSession(root, launched, repoUrl) {
+function saveSession(root, launched, repoUrl, ref) {
   const session = {
     launched,
     started_at: new Date().toISOString(),
     ide: 'cursor',
-    repo: repoUrl
+    repo: repoUrl,
+    ref
   };
   const sessionPath = join(root, '.agentxchain-session.json');
   writeFileSync(sessionPath, JSON.stringify(session, null, 2) + '\n');
@@ -160,29 +176,5 @@ function filterAgents(config, specificId) {
   return config.agents;
 }
 
-function fallbackPromptOutput(config, opts) {
-  const agents = filterAgents(config, opts.agent);
-  console.log(chalk.bold('  No API key. Printing seed prompts for manual use:'));
-  console.log('');
-  for (const [id, agent] of Object.entries(agents)) {
-    const prompt = generateSeedPrompt(id, agent, config);
-    console.log(chalk.dim('  ' + '─'.repeat(50)));
-    console.log(chalk.cyan(`  Agent: ${chalk.bold(id)} (${agent.name})`));
-    console.log(chalk.dim('  ' + '─'.repeat(50)));
-    console.log('');
-    console.log(prompt);
-    console.log('');
-  }
-  return [];
-}
-
-function printApiKeyHelp() {
-  console.log('');
-  console.log(chalk.yellow('  CURSOR_API_KEY not found.'));
-  console.log('');
-  console.log(`  1. Go to ${chalk.cyan('cursor.com/settings')} → Cloud Agents`);
-  console.log('  2. Create an API key');
-  console.log(`  3. Add to .env: ${chalk.bold('CURSOR_API_KEY=your_key')}`);
-  console.log(`  4. Run: ${chalk.bold('source .env && agentxchain start')}`);
-  console.log('');
-}
+// No prompt fallback here by design.
+// Cursor mode is strict: an API key is required.

package/src/commands/branch.js

@@ -0,0 +1,98 @@
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { loadConfig, CONFIG_FILE } from '../lib/config.js';
+import { getCurrentBranch } from '../lib/repo.js';
+
+export async function branchCommand(name, opts) {
+  const result = loadConfig();
+  if (!result) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = result;
+  const configPath = join(root, CONFIG_FILE);
+  const currentGitBranch = getCurrentBranch(root) || 'main';
+  const hasOverride = !!config.cursor?.ref;
+  const overrideBranch = hasOverride ? config.cursor.ref : null;
+
+  if (opts.unset && (name || opts.useCurrent)) {
+    console.log(chalk.red('  Use either --unset OR a branch value, not both.'));
+    process.exit(1);
+  }
+
+  if (name && opts.useCurrent) {
+    console.log(chalk.red('  Use either --use-current OR a branch value, not both.'));
+    process.exit(1);
+  }
+
+  if (opts.unset) {
+    if (config.cursor?.ref) {
+      delete config.cursor.ref;
+      if (config.cursor && Object.keys(config.cursor).length === 0) delete config.cursor;
+      saveConfig(configPath, config);
+    }
+
+    console.log('');
+    console.log(chalk.green('  ✓ Cleared branch override.'));
+    console.log(chalk.dim(`  Effective branch now follows git: ${currentGitBranch}`));
+    console.log('');
+    return;
+  }
+
+  if (opts.useCurrent) {
+    setBranchOverride(config, configPath, currentGitBranch);
+    console.log('');
+    console.log(chalk.green(`  ✓ Set Cursor branch override to current git branch: ${chalk.bold(currentGitBranch)}`));
+    console.log('');
+    return;
+  }
+
+  if (name) {
+    const branch = String(name).trim();
+    if (!branch) {
+      console.log(chalk.red('  Branch cannot be empty.'));
+      process.exit(1);
+    }
+    if (!/^[A-Za-z0-9._/-]+$/.test(branch)) {
+      console.log(chalk.red('  Invalid branch name. Use letters, numbers, ., _, -, /.'));
+      process.exit(1);
+    }
+
+    setBranchOverride(config, configPath, branch);
+    console.log('');
+    console.log(chalk.green(`  ✓ Set Cursor branch override: ${chalk.bold(branch)}`));
+    if (branch !== currentGitBranch) {
+      console.log(chalk.dim(`    (current git branch is ${currentGitBranch})`));
+    }
+    console.log('');
+    return;
+  }
+
+  const effective = overrideBranch || currentGitBranch;
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Branch'));
+  console.log(chalk.dim('  ' + '─'.repeat(36)));
+  console.log('');
+  console.log(`  ${chalk.dim('Current git branch:')} ${currentGitBranch}`);
+  console.log(`  ${chalk.dim('Cursor override:')}    ${overrideBranch || chalk.dim('none')}`);
+  console.log(`  ${chalk.dim('Effective branch:')}   ${chalk.bold(effective)}`);
+  console.log('');
+  console.log(chalk.dim('  Commands:'));
+  console.log(`    ${chalk.bold('agentxchain branch')}               Show effective branch`);
+  console.log(`    ${chalk.bold('agentxchain branch <name>')}        Set branch override`);
+  console.log(`    ${chalk.bold('agentxchain branch --use-current')} Set override to current git branch`);
+  console.log(`    ${chalk.bold('agentxchain branch --unset')}       Follow git branch automatically`);
+  console.log('');
+}
+
+function setBranchOverride(config, configPath, branch) {
+  if (!config.cursor) config.cursor = {};
+  config.cursor.ref = branch;
+  saveConfig(configPath, config);
+}
+
+function saveConfig(configPath, config) {
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}

package/src/commands/claim.js

@@ -3,6 +3,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
 import { stopAgent, sendFollowup, loadSession } from '../adapters/cursor.js';
+import { getCursorApiKey, printCursorApiKeyRequired } from '../lib/cursor-api-key.js';
 
 export async function claimCommand(opts) {
   const result = loadConfig();
@@ -12,9 +13,17 @@ export async function claimCommand(opts) {
   const lock = loadLock(root);
   if (!lock) { console.log(chalk.red('  lock.json not found.')); process.exit(1); }
 
-  const apiKey = process.env.CURSOR_API_KEY;
+  const apiKey = getCursorApiKey(root);
   const session = loadSession(root);
-  const hasCursor = session?.ide === 'cursor' && apiKey;
+  const hasCursorSession = session?.ide === 'cursor' && session?.launched?.length > 0;
+  const hasCursor = hasCursorSession && apiKey;
+
+  if (hasCursorSession && !apiKey) {
+    printCursorApiKeyRequired('`agentxchain claim` with Cursor agents');
+    console.log(chalk.dim('  Claim aborted so agents are not left running unexpectedly.'));
+    console.log('');
+    process.exit(1);
+  }
 
   if (lock.holder === 'human') {
     console.log('');
@@ -62,7 +71,7 @@ export async function claimCommand(opts) {
   console.log('');
 }
 
-export async function releaseCommand() {
+export async function releaseCommand(opts) {
   const result = loadConfig();
   if (!result) { console.log(chalk.red('  No agentxchain.json found.')); process.exit(1); }
 
@@ -75,7 +84,18 @@ export async function releaseCommand() {
     return;
   }
 
+  if (lock.holder !== 'human' && !opts.force) {
+    const name = config.agents[lock.holder]?.name || lock.holder;
+    console.log('');
+    console.log(chalk.red(`  Lock is held by ${chalk.bold(lock.holder)} (${name}), not human.`));
+    console.log(chalk.dim('  Refusing to release another holder without explicit override.'));
+    console.log(chalk.dim('  Use `agentxchain release --force` if you really want to break this lock.'));
+    console.log('');
+    process.exit(1);
+  }
+
   const who = lock.holder;
+  const priorLastReleasedBy = lock.last_released_by;
   const lockPath = join(root, LOCK_FILE);
   const newLock = {
     holder: null,
@@ -90,12 +110,25 @@ export async function releaseCommand() {
 
   // If releasing from human and Cursor session exists, wake the next agent
   if (who === 'human') {
-    const apiKey = process.env.CURSOR_API_KEY;
+    const apiKey = getCursorApiKey(root);
     const session = loadSession(root);
+    const hasCursorSession = session?.ide === 'cursor' && session?.launched?.length > 0;
+
+    if (hasCursorSession && !apiKey) {
+      printCursorApiKeyRequired('`agentxchain release` with Cursor agents');
+      console.log(chalk.dim('  Lock released, but wake-up followup was skipped due to missing key.'));
+      console.log(chalk.dim('  Start `agentxchain watch` after setting the key.'));
+      console.log('');
+      return;
+    }
 
     if (session?.ide === 'cursor' && apiKey) {
-      const agentIds = Object.keys(config.agents);
-      const next = agentIds[0];
+      const next = pickNextAgent(priorLastReleasedBy, config);
+      if (!next) {
+        console.log(chalk.dim('  No agents configured to wake.'));
+        console.log('');
+        return;
+      }
       const cloudAgent = session.launched.find(a => a.id === next);
 
       if (cloudAgent) {
@@ -115,3 +148,12 @@ export async function releaseCommand() {
 
   console.log('');
 }
+
+function pickNextAgent(lastReleasedBy, config) {
+  const agentIds = Object.keys(config.agents || {});
+  if (agentIds.length === 0) return null;
+  if (!lastReleasedBy || !agentIds.includes(lastReleasedBy)) return agentIds[0];
+
+  const idx = agentIds.indexOf(lastReleasedBy);
+  return agentIds[(idx + 1) % agentIds.length];
+}

package/src/commands/config.js

@@ -102,6 +102,11 @@ function removeAgent(config, configPath, id) {
   }
 
   const name = config.agents[id].name;
+  if (Object.keys(config.agents).length <= 1) {
+    console.log(chalk.red('  Cannot remove the last agent.'));
+    console.log(chalk.dim('  Add another agent first, then remove this one if needed.'));
+    process.exit(1);
+  }
   delete config.agents[id];
   writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 

package/src/commands/init.js

@@ -205,6 +205,25 @@ export async function initCommand(opts) {
   writeFileSync(join(dir, 'history.jsonl'), '');
   writeFileSync(join(dir, 'log.md'), `# ${project} — Agent Log\n\n## COMPRESSED CONTEXT\n\n(No compressed context yet.)\n\n## MESSAGE LOG\n\n(Agents append messages below this line.)\n`);
   writeFileSync(join(dir, 'HUMAN_TASKS.md'), '# Human Tasks\n\n(Agents append tasks here when they need human action.)\n');
+  writeFileSync(join(dir, '.env.example'), 'CURSOR_API_KEY=\n');
+  if (!existsSync(join(dir, '.env'))) {
+    writeFileSync(
+      join(dir, '.env'),
+      '# Required for Cursor commands: start/watch/stop/claim/release\nCURSOR_API_KEY=\n'
+    );
+  }
+  const gitignorePath = join(dir, '.gitignore');
+  const requiredIgnores = ['.env', '.agentxchain-session.json', '.agentxchain-trigger.json'];
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, requiredIgnores.join('\n') + '\n');
+  } else {
+    const existingIgnore = readFileSync(gitignorePath, 'utf8');
+    const missing = requiredIgnores.filter(entry => !existingIgnore.split(/\r?\n/).includes(entry));
+    if (missing.length > 0) {
+      const prefix = existingIgnore.endsWith('\n') ? '' : '\n';
+      writeFileSync(gitignorePath, existingIgnore + prefix + missing.join('\n') + '\n');
+    }
+  }
 
   // .planning/ structure
   mkdirSync(join(dir, '.planning', 'research'), { recursive: true });
@@ -245,7 +264,8 @@ export async function initCommand(opts) {
   console.log('');
   console.log(`  ${chalk.cyan('Next:')}`);
   console.log(`    ${chalk.bold(`cd ${folderName}`)}`);
+  console.log(`    ${chalk.bold('edit .env')}            ${chalk.dim('# set CURSOR_API_KEY (required for Cursor mode)')}`);
+  console.log(`    ${chalk.bold('agentxchain start')}    ${chalk.dim('# launch agents in Cursor')}`);
   console.log(`    ${chalk.bold('agentxchain watch')}    ${chalk.dim('# start the referee')}`);
-  console.log(`    ${chalk.bold('agentxchain start')}    ${chalk.dim('# launch agents in your IDE')}`);
   console.log('');
 }

package/src/commands/start.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
-import ora from 'ora';
 import { loadConfig } from '../lib/config.js';
 import { generateSeedPrompt } from '../lib/seed-prompt.js';
+import { getCursorApiKey, printCursorApiKeyRequired } from '../lib/cursor-api-key.js';
 
 export async function startCommand(opts) {
   const result = loadConfig();
@@ -11,9 +11,22 @@ export async function startCommand(opts) {
   }
 
   const { root, config } = result;
-  const agentCount = Object.keys(config.agents).length;
+  const agentIds = Object.keys(config.agents || {});
+  const agentCount = agentIds.length;
   const ide = opts.ide;
 
+  if (agentCount === 0) {
+    console.log(chalk.red('  No agents configured in agentxchain.json.'));
+    console.log(chalk.dim('  Add an agent with: agentxchain config --add-agent'));
+    process.exit(1);
+  }
+
+  if (opts.agent && !config.agents?.[opts.agent]) {
+    console.log(chalk.red(`  Agent "${opts.agent}" not found in agentxchain.json.`));
+    console.log(chalk.dim(`  Available: ${agentIds.join(', ')}`));
+    process.exit(1);
+  }
+
   console.log('');
   console.log(chalk.bold(`  Launching ${agentCount} agents via ${ide}`));
   console.log(chalk.dim(`  Project: ${config.project}`));
@@ -33,6 +46,11 @@ export async function startCommand(opts) {
 
   switch (ide) {
     case 'cursor': {
+      const apiKey = getCursorApiKey(root);
+      if (!apiKey) {
+        printCursorApiKeyRequired('`agentxchain start --ide cursor`');
+        process.exit(1);
+      }
       const { launchCursorAgents } = await import('../adapters/cursor.js');
       await launchCursorAgents(config, root, opts);
       break;

package/src/commands/status.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { loadConfig, loadLock, loadState } from '../lib/config.js';
 import { getAgentStatus, loadSession } from '../adapters/cursor.js';
+import { getCursorApiKey } from '../lib/cursor-api-key.js';
 
 export async function statusCommand(opts) {
   const result = loadConfig();
@@ -52,13 +53,16 @@ export async function statusCommand(opts) {
 
   // Cursor session info
   const session = loadSession(root);
-  const apiKey = process.env.CURSOR_API_KEY;
+  const apiKey = getCursorApiKey(root);
   const hasCursor = session?.ide === 'cursor' && session?.launched?.length > 0;
 
   if (hasCursor) {
     console.log(`  ${chalk.dim('Cursor:')}   ${chalk.cyan('Active session')} (${session.launched.length} agents)`);
     console.log(`  ${chalk.dim('Started:')}  ${session.started_at}`);
     if (session.repo) console.log(`  ${chalk.dim('Repo:')}     ${session.repo}`);
+    if (!apiKey) {
+      console.log(`  ${chalk.dim('API key:')}  ${chalk.red('Missing')} (set CURSOR_API_KEY in .env for live statuses)`);
+    }
     console.log('');
   }
 

package/src/commands/stop.js

@@ -2,7 +2,8 @@ import { readFileSync, existsSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig } from '../lib/config.js';
-import { deleteAgent, stopAgent, loadSession } from '../adapters/cursor.js';
+import { deleteAgent, loadSession } from '../adapters/cursor.js';
+import { getCursorApiKey, printCursorApiKeyRequired } from '../lib/cursor-api-key.js';
 
 const SESSION_FILE = '.agentxchain-session.json';
 
@@ -22,24 +23,29 @@ export async function stopCommand() {
   console.log('');
   console.log(chalk.bold(`  Stopping ${session.launched.length} agents (${session.ide})`));
   console.log('');
+  let allStopped = true;
 
   if (session.ide === 'cursor') {
-    const apiKey = process.env.CURSOR_API_KEY;
+    const apiKey = getCursorApiKey(root);
     if (!apiKey) {
-      console.log(chalk.yellow('  CURSOR_API_KEY not set. Cannot stop agents via API.'));
-      console.log(chalk.dim('  Stop them manually at cursor.com/agents'));
-    } else {
-      for (const agent of session.launched) {
-        try {
-          const deleted = await deleteAgent(apiKey, agent.cloudId);
-          if (deleted) {
-            console.log(chalk.green(`  ✓ Deleted ${chalk.bold(agent.id)} (${agent.cloudId})`));
-          } else {
-            console.log(chalk.yellow(`  ⚠ Could not delete ${agent.id} — may already be gone`));
-          }
-        } catch (err) {
-          console.log(chalk.red(`  ✗ ${agent.id}: ${err.message}`));
+      printCursorApiKeyRequired('`agentxchain stop` for Cursor agents');
+      console.log(chalk.dim('  Session file was kept so you can retry after setting the key.'));
+      console.log('');
+      return;
+    }
+
+    for (const agent of session.launched) {
+      try {
+        const deleted = await deleteAgent(apiKey, agent.cloudId);
+        if (deleted) {
+          console.log(chalk.green(`  ✓ Deleted ${chalk.bold(agent.id)} (${agent.cloudId})`));
+        } else {
+          console.log(chalk.yellow(`  ⚠ Could not delete ${agent.id} — may already be gone`));
+          allStopped = false;
         }
+      } catch (err) {
+        console.log(chalk.red(`  ✗ ${agent.id}: ${err.message}`));
+        allStopped = false;
       }
     }
   } else if (session.ide === 'claude-code') {
@@ -53,18 +59,22 @@ export async function stopCommand() {
             console.log(chalk.dim(`  ${agent.id} (PID: ${agent.pid}) — already stopped`));
           } else {
             console.log(chalk.red(`  ✗ ${agent.id}: ${err.message}`));
+            allStopped = false;
           }
         }
       }
     }
   }
 
-  // Remove session file
-  const sessionPath = join(root, SESSION_FILE);
-  if (existsSync(sessionPath)) unlinkSync(sessionPath);
-
   console.log('');
-  console.log(chalk.dim('  Session file removed.'));
-  console.log(chalk.green('  All agents stopped.'));
+  const sessionPath = join(root, SESSION_FILE);
+  if (allStopped) {
+    if (existsSync(sessionPath)) unlinkSync(sessionPath);
+    console.log(chalk.dim('  Session file removed.'));
+    console.log(chalk.green('  All agents stopped.'));
+  } else {
+    console.log(chalk.yellow('  Some agents could not be stopped.'));
+    console.log(chalk.dim('  Session file was kept so you can retry `agentxchain stop`.'));
+  }
   console.log('');
 }

package/src/commands/watch.js

@@ -1,11 +1,19 @@
 import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'fs';
-import { join } from 'path';
+import { join, dirname } from 'path';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
 import { notifyHuman as sendNotification } from '../lib/notify.js';
 import { sendFollowup, getAgentStatus, stopAgent, loadSession } from '../adapters/cursor.js';
+import { getCursorApiKey, printCursorApiKeyRequired } from '../lib/cursor-api-key.js';
 
 export async function watchCommand(opts) {
+  if (opts.daemon && process.env.AGENTXCHAIN_WATCH_DAEMON !== '1') {
+    startWatchDaemon();
+    return;
+  }
+
   const result = loadConfig();
   if (!result) {
     console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
@@ -16,10 +24,20 @@ export async function watchCommand(opts) {
   const interval = config.rules?.watch_interval_ms || 5000;
   const ttlMinutes = config.rules?.ttl_minutes || 10;
   const agentIds = Object.keys(config.agents);
-  const apiKey = process.env.CURSOR_API_KEY;
+  if (agentIds.length === 0) {
+    console.log(chalk.red('  No agents configured in agentxchain.json.'));
+    console.log(chalk.dim('  Add an agent with: agentxchain config --add-agent'));
+    process.exit(1);
+  }
+  const apiKey = getCursorApiKey(root);
   const session = loadSession(root);
   const hasCursorSession = session?.ide === 'cursor' && session?.launched?.length > 0;
 
+  if (hasCursorSession && !apiKey) {
+    printCursorApiKeyRequired('`agentxchain watch` with a Cursor session');
+    process.exit(1);
+  }
+
   console.log('');
   console.log(chalk.bold('  AgentXchain Watch'));
   console.log(chalk.dim(`  Project: ${config.project}`));
@@ -102,12 +120,19 @@ export async function watchCommand(opts) {
       if (stateKey !== lastState) {
         const next = pickNextAgent(lock, config);
         log('free', `Lock free (released by ${lock.last_released_by || 'none'}). Waking ${chalk.bold(next)}.`);
-        lastState = stateKey;
+        let wakeSucceeded = false;
 
         if (hasCursorSession && apiKey) {
-          await wakeCursorAgent(apiKey, session, next, lock, config);
+          wakeSucceeded = await wakeCursorAgent(apiKey, session, next, lock, config, root);
         } else {
           writeTrigger(root, next, lock, config);
+          wakeSucceeded = true;
+        }
+
+        if (wakeSucceeded) {
+          lastState = stateKey;
+        } else {
+          log('warn', `Wake for ${next} failed. Will retry next poll.`);
         }
       }
     } catch (err) {
@@ -126,11 +151,12 @@ export async function watchCommand(opts) {
   });
 }
 
-async function wakeCursorAgent(apiKey, session, agentId, lock, config) {
+async function wakeCursorAgent(apiKey, session, agentId, lock, config, root) {
   const cloudAgent = session.launched.find(a => a.id === agentId);
   if (!cloudAgent) {
     log('warn', `No Cursor cloud agent found for "${agentId}". Using trigger file.`);
-    return;
+    writeTrigger(root, agentId, lock, config);
+    return true;
   }
 
   const name = config.agents[agentId]?.name || agentId;
@@ -152,13 +178,16 @@ This must be the last thing you write. The watch process will wake the next agen
   try {
     await sendFollowup(apiKey, cloudAgent.cloudId, wakeMessage);
     log('wake', `Sent followup to ${chalk.bold(agentId)} (${cloudAgent.cloudId})`);
+    return true;
   } catch (err) {
     log('error', `Failed to wake ${agentId}: ${err.message}`);
+    return false;
   }
 }
 
 function pickNextAgent(lock, config) {
   const agentIds = Object.keys(config.agents);
+  if (agentIds.length === 0) return null;
   const lastAgent = lock.last_released_by;
 
   if (!lastAgent || !agentIds.includes(lastAgent)) return agentIds[0];
@@ -185,6 +214,7 @@ function forceRelease(root, lock, staleAgent, config) {
 }
 
 function writeTrigger(root, agentId, lock, config) {
+  if (!agentId) return;
   const triggerPath = join(root, '.agentxchain-trigger.json');
   writeFileSync(triggerPath, JSON.stringify({
     agent: agentId,
@@ -208,3 +238,20 @@ function log(type, msg) {
   };
   console.log(`  ${chalk.dim(time)} ${tags[type] || chalk.dim(type)}  ${msg}`);
 }
+
+function startWatchDaemon() {
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  const cliBin = join(currentDir, '../../bin/agentxchain.js');
+  const child = spawn(process.execPath, [cliBin, 'watch'], {
+    cwd: process.cwd(),
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, AGENTXCHAIN_WATCH_DAEMON: '1' }
+  });
+  child.unref();
+
+  console.log('');
+  console.log(chalk.green(`  ✓ Watch started in daemon mode (PID: ${child.pid})`));
+  console.log(chalk.dim('  Use `agentxchain stop` or kill the PID to stop it.'));
+  console.log('');
+}

package/src/lib/cursor-api-key.js

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+
+function parseEnvFile(raw) {
+  const out = {};
+  const lines = raw.split(/\r?\n/);
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    if (key) out[key] = value;
+  }
+
+  return out;
+}
+
+export function hydrateEnvFromProject(root) {
+  if (!root) return;
+
+  const envPath = join(root, '.env');
+  if (!existsSync(envPath)) return;
+
+  try {
+    const parsed = parseEnvFile(readFileSync(envPath, 'utf8'));
+    for (const [k, v] of Object.entries(parsed)) {
+      if (!process.env[k] && v !== undefined) process.env[k] = v;
+    }
+  } catch {
+    // Non-fatal: commands still work with shell env vars.
+  }
+}
+
+export function getCursorApiKey(root) {
+  hydrateEnvFromProject(root);
+  const key = process.env.CURSOR_API_KEY?.trim();
+  return key || null;
+}
+
+export function printCursorApiKeyRequired(commandName = 'this command') {
+  console.log('');
+  console.log(chalk.red(`  CURSOR_API_KEY is required for ${commandName}.`));
+  console.log(chalk.dim('  Set it once in your project root .env file:'));
+  console.log(`  ${chalk.bold('CURSOR_API_KEY=your_key')}`);
+  console.log(chalk.dim('  You can get a key from: cursor.com/settings -> Cloud Agents'));
+  console.log('');
+}

package/src/lib/repo.js

@@ -2,7 +2,11 @@ import { execSync } from 'child_process';
 
 export async function getRepoUrl(root) {
   try {
-    const raw = execSync('git remote get-url origin', { cwd: root, encoding: 'utf8' }).trim();
+    const raw = execSync('git remote get-url origin', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
 
     // Convert SSH to HTTPS if needed
     // git@github.com:user/repo.git -> https://github.com/user/repo
@@ -11,18 +15,17 @@ export async function getRepoUrl(root) {
       return `https://github.com/${path}`;
     }
 
-    // Already HTTPS — strip .git suffix
-    if (raw.includes('github.com')) {
-      return raw.replace(/\.git$/, '');
-    }
+    // Strip embedded credentials/tokens from HTTPS URLs.
+    // https://x-access-token:TOKEN@github.com/org/repo.git -> https://github.com/org/repo
+    // https://user:pass@github.com/org/repo.git -> https://github.com/org/repo
+    const credentialStripped = raw.replace(/^https?:\/\/[^/@]+@github\.com\//, 'https://github.com/');
 
-    // Strip tokens from URL (x-access-token:TOKEN@github.com)
-    if (raw.includes('x-access-token')) {
-      const cleaned = raw.replace(/https:\/\/x-access-token:[^@]+@/, 'https://');
-      return cleaned.replace(/\.git$/, '');
+    // Already HTTPS — strip .git suffix
+    if (credentialStripped.includes('github.com')) {
+      return credentialStripped.replace(/\.git$/, '');
     }
 
-    return raw;
+    return credentialStripped;
   } catch {
     return null;
   }
@@ -30,8 +33,24 @@ export async function getRepoUrl(root) {
 
 export function getCurrentBranch(root) {
   try {
-    return execSync('git rev-parse --abbrev-ref HEAD', { cwd: root, encoding: 'utf8' }).trim();
+    const current = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    if (current && current !== 'HEAD') return current;
+  } catch {}
+
+  try {
+    const remoteHead = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    if (remoteHead.includes('/')) return remoteHead.split('/').pop();
   } catch {
     return 'main';
   }
+
+  return 'main';
 }