agentxchain 0.4.1 → 0.4.3

package/README.md

@@ -20,11 +20,13 @@ npx agentxchain init
 agentxchain init                      # create a project (template selection)
 cd my-project/
 echo "CURSOR_API_KEY=your_key" >> .env # from cursor.com/settings -> Cloud Agents
+# In Cursor, connect GitHub account (needed for private repos)
+# Cursor Settings -> GitHub integration
 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).
+> `CURSOR_API_KEY` is required for Cursor commands (`start/watch/stop/claim/release` when using Cursor sessions). Your Cursor account also needs GitHub access to the target repository.
 
 ## Commands
 
@@ -52,6 +54,13 @@ 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
@@ -74,7 +83,7 @@ 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.
+If `NPM_TOKEN` exists in `agentXchain.dev/.env` (project root), the script uses it automatically.
 
 ## Links
 

package/bin/agentxchain.js

@@ -16,7 +16,7 @@ const program = new Command();
 program
   .name('agentxchain')
   .description('Multi-agent coordination in your IDE')
-  .version('0.4.0');
+  .version('0.4.1');
 
 program
   .command('init')
@@ -74,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.1",
+  "version": "0.4.3",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {

package/src/adapters/cursor.js

@@ -91,6 +91,8 @@ export async function launchCursorAgents(config, root, opts) {
     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(chalk.dim('  If the branch exists on GitHub, verify your Cursor account has GitHub access'));
+    console.log(chalk.dim('  to this repository (Cursor Settings -> GitHub integration).'));
     console.log('');
   }
 

package/src/commands/claim.js

@@ -71,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); }
 
@@ -84,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,
@@ -112,8 +123,12 @@ export async function releaseCommand() {
     }
 
     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) {
@@ -133,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/start.js

@@ -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}`));

package/src/commands/stop.js

@@ -23,6 +23,7 @@ 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 = getCursorApiKey(root);
@@ -40,9 +41,11 @@ export async function stopCommand() {
           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') {
@@ -56,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,5 +1,7 @@
 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';
@@ -7,6 +9,11 @@ import { sendFollowup, getAgentStatus, stopAgent, loadSession } from '../adapter
 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.'));
@@ -17,6 +24,11 @@ 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);
+  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;
@@ -108,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) {
@@ -132,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;
@@ -158,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];
@@ -191,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,
@@ -214,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/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,12 +33,20 @@ export async function getRepoUrl(root) {
 
 export function getCurrentBranch(root) {
   try {
-    const current = 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' }).trim();
+    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';