agentxchain 0.8.6 → 0.8.8

package/src/commands/claim.js

@@ -1,7 +1,10 @@
-import { writeFileSync, existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
+import { safeWriteJson } from '../lib/safe-write.js';
+import { resolveExpectedClaimer } from '../lib/next-owner.js';
+import { runConfiguredVerify } from '../lib/verify-command.js';
 
 export async function claimCommand(opts) {
   const result = loadConfig();
@@ -39,7 +42,12 @@ export async function claimCommand(opts) {
     turn_number: lock.turn_number,
     claimed_at: new Date().toISOString()
   };
-  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  safeWriteJson(lockPath, newLock);
+  const verify = loadLock(root);
+  if (verify?.holder !== 'human') {
+    console.log(chalk.red(`  Claim race: expected holder=human, got ${verify?.holder}. Another process won.`));
+    process.exit(1);
+  }
   clearBlockedState(root);
 
   console.log('');
@@ -75,6 +83,11 @@ export async function releaseCommand(opts) {
   }
 
   const who = lock.holder;
+  const verifyResult = runConfiguredVerify(config, root);
+  if (!verifyResult.ok) {
+    console.log(chalk.red(`  Verification failed: ${verifyResult.command}`));
+    process.exit(1);
+  }
   const lockPath = join(root, LOCK_FILE);
   const newLock = {
     holder: null,
@@ -82,14 +95,19 @@ export async function releaseCommand(opts) {
     turn_number: who === 'human' ? lock.turn_number : lock.turn_number + 1,
     claimed_at: null
   };
-  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  safeWriteJson(lockPath, newLock);
+  const verify = loadLock(root);
+  if (verify?.holder !== null || verify?.last_released_by !== who || verify?.turn_number !== newLock.turn_number) {
+    console.log(chalk.red('  Release race: lock.json changed unexpectedly after release attempt.'));
+    process.exit(1);
+  }
   if (who === 'human') {
     clearBlockedState(root);
   }
 
   console.log('');
   console.log(chalk.green(`  ✓ Lock released by ${chalk.bold(who)} (turn ${newLock.turn_number})`));
-  console.log(chalk.dim('  The Stop hook will coordinate the next agent turn in VS Code.'));
+  console.log(chalk.dim('  Next turn will be coordinated by the VS Code Stop hook or watch/supervise.'));
   console.log('');
 }
 
@@ -106,12 +124,26 @@ function claimAsAgent({ opts, root, config, lock }) {
     process.exit(1);
   }
 
-  const expected = pickNextAgent(lock, config);
+  const expected = pickNextAgent(root, lock, config);
+  if (!opts.force && config.rules?.strict_next_owner && (expected === null || expected === undefined)) {
+    console.log(chalk.red('  No next owner resolved. Add a valid `Next owner: <agent_id>` line to TALK.md, or set rules.strict_next_owner to false.'));
+    process.exit(1);
+  }
   if (!opts.force && expected && expected !== agentId) {
     console.log(chalk.red(`  Out-of-turn claim blocked. Expected: ${expected}, got: ${agentId}.`));
     process.exit(1);
   }
 
+  const maxClaims = Number(config.rules?.max_consecutive_claims || 0);
+  if (!opts.force && maxClaims > 0 && lock.last_released_by === agentId) {
+    const consecutiveTurns = countRecentTurnsByAgent(root, config, agentId);
+    if (consecutiveTurns >= maxClaims) {
+      console.log(chalk.red(`  Consecutive-claim limit reached for "${agentId}" (${consecutiveTurns}/${maxClaims}).`));
+      console.log(chalk.dim('  Hand off to another agent or use --force for recovery only.'));
+      process.exit(1);
+    }
+  }
+
   const lockPath = join(root, LOCK_FILE);
   const next = {
     holder: agentId,
@@ -119,7 +151,14 @@ function claimAsAgent({ opts, root, config, lock }) {
     turn_number: lock.turn_number,
     claimed_at: new Date().toISOString()
   };
-  writeFileSync(lockPath, JSON.stringify(next, null, 2) + '\n');
+  safeWriteJson(lockPath, next);
+
+  const verify = loadLock(root);
+  if (verify?.holder !== agentId) {
+    console.log(chalk.red(`  Claim race: expected holder=${agentId}, got ${verify?.holder}. Another process won.`));
+    process.exit(1);
+  }
+
   console.log(chalk.green(`  ✓ Lock claimed by ${agentId} (turn ${next.turn_number})`));
 }
 
@@ -134,6 +173,12 @@ function releaseAsAgent({ opts, root, config, lock }) {
     process.exit(1);
   }
 
+  const verifyResult = runConfiguredVerify(config, root);
+  if (!verifyResult.ok) {
+    console.log(chalk.red(`  Verification failed: ${verifyResult.command}`));
+    process.exit(1);
+  }
+
   const lockPath = join(root, LOCK_FILE);
   const next = {
     holder: null,
@@ -141,17 +186,21 @@ function releaseAsAgent({ opts, root, config, lock }) {
     turn_number: lock.turn_number + 1,
     claimed_at: null
   };
-  writeFileSync(lockPath, JSON.stringify(next, null, 2) + '\n');
+  safeWriteJson(lockPath, next);
+  const verifyRelease = loadLock(root);
+  if (
+    verifyRelease?.holder !== null ||
+    verifyRelease?.last_released_by !== agentId ||
+    verifyRelease?.turn_number !== next.turn_number
+  ) {
+    console.log(chalk.red('  Release race: lock.json changed unexpectedly after release attempt.'));
+    process.exit(1);
+  }
   console.log(chalk.green(`  ✓ Lock released by ${agentId} (turn ${next.turn_number})`));
 }
 
-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];
-  const lastIndex = agentIds.indexOf(lastAgent);
-  return agentIds[(lastIndex + 1) % agentIds.length];
+function pickNextAgent(root, lock, config) {
+  return resolveExpectedClaimer(root, config, lock).next;
 }
 
 function clearBlockedState(root) {
@@ -161,7 +210,29 @@ function clearBlockedState(root) {
     const state = JSON.parse(readFileSync(statePath, 'utf8'));
     if (state.blocked || state.blocked_on) {
       const next = { ...state, blocked: false, blocked_on: null };
-      writeFileSync(statePath, JSON.stringify(next, null, 2) + '\n');
+      safeWriteJson(statePath, next);
     }
   } catch {}
 }
+
+function countRecentTurnsByAgent(root, config, agentId) {
+  const historyPath = join(root, config.history_file || 'history.jsonl');
+  if (!existsSync(historyPath)) return 0;
+
+  try {
+    const lines = readFileSync(historyPath, 'utf8')
+      .split(/\r?\n/)
+      .map(line => line.trim())
+      .filter(Boolean);
+
+    let count = 0;
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      const entry = JSON.parse(lines[i]);
+      if (entry?.agent !== agentId) break;
+      count += 1;
+    }
+    return count;
+  } catch {
+    return 0;
+  }
+}

package/src/commands/config.js

@@ -3,6 +3,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { loadConfig, CONFIG_FILE } from '../lib/config.js';
+import { validateConfigSchema } from '../lib/schema.js';
 
 export async function configCommand(opts) {
   const result = loadConfig();
@@ -127,6 +128,12 @@ function setSetting(config, configPath, keyValPair) {
   const key = parts[0];
   const rawVal = parts.slice(1).join(' ');
   const segments = key.split('.');
+  const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
+
+  if (segments.some(segment => forbiddenKeys.has(segment))) {
+    console.log(chalk.red('  Refusing to write reserved object path.'));
+    process.exit(1);
+  }
 
   let target = config;
   for (let i = 0; i < segments.length - 1; i++) {
@@ -145,6 +152,15 @@ function setSetting(config, configPath, keyValPair) {
   else if (!isNaN(rawVal) && rawVal !== '') val = Number(rawVal);
 
   target[lastKey] = val;
+  const validation = validateConfigSchema(config);
+  if (!validation.ok) {
+    target[lastKey] = oldVal;
+    if (oldVal === undefined) {
+      delete target[lastKey];
+    }
+    console.log(chalk.red(`  Refusing to save invalid config: ${validation.errors.join(', ')}`));
+    process.exit(1);
+  }
   writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 
   console.log('');

package/src/commands/doctor.js

@@ -4,6 +4,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock } from '../lib/config.js';
 import { validateProject } from '../lib/validation.js';
+import { getWatchPid } from './watch.js';
 
 export async function doctorCommand() {
   const result = loadConfig();
@@ -86,9 +87,16 @@ function checkPm(config) {
 }
 
 function checkWatchProcess() {
+  const result = loadConfig();
+  if (result) {
+    const pid = getWatchPid(result.root);
+    if (pid) {
+      return { name: 'watch process', level: 'pass', detail: `watch running (PID: ${pid})` };
+    }
+  }
   try {
     execSync('pgrep -f "agentxchain.*watch" >/dev/null', { stdio: 'ignore' });
-    return { name: 'watch process', level: 'pass', detail: 'watch appears to be running' };
+    return { name: 'watch process', level: 'pass', detail: 'watch appears to be running (no PID file)' };
   } catch {
     return { name: 'watch process', level: 'warn', detail: 'watch not running (start with `agentxchain watch` or `agentxchain supervise --autonudge`)' };
   }

package/src/commands/init.js

@@ -52,7 +52,12 @@ export async function initCommand(opts) {
     project = 'My AgentXchain project';
     agents = DEFAULT_AGENTS;
     folderName = slugify(project);
-    rules = { max_consecutive_claims: 2, require_message: true, compress_after_words: 5000 };
+    rules = {
+      max_consecutive_claims: 2,
+      require_message: true,
+      compress_after_words: 5000,
+      strict_next_owner: false
+    };
   } else {
     const templates = loadTemplates();
 
@@ -86,7 +91,12 @@ export async function initCommand(opts) {
       project = projectName;
     } else if (template === 'default') {
       agents = DEFAULT_AGENTS;
-      rules = { max_consecutive_claims: 2, require_message: true, compress_after_words: 5000 };
+      rules = {
+      max_consecutive_claims: 2,
+      require_message: true,
+      compress_after_words: 5000,
+      strict_next_owner: false
+    };
       const { projectName } = await inquirer.prompt([{
         type: 'input',
         name: 'projectName',
@@ -103,7 +113,12 @@ export async function initCommand(opts) {
       }]);
       project = projectName;
       agents = {};
-      rules = { max_consecutive_claims: 2, require_message: true, compress_after_words: 5000 };
+      rules = {
+      max_consecutive_claims: 2,
+      require_message: true,
+      compress_after_words: 5000,
+      strict_next_owner: false
+    };
 
       const { count } = await inquirer.prompt([{
         type: 'number',
@@ -192,6 +207,7 @@ export async function initCommand(opts) {
       compress_after_words: rules.compress_after_words || 5000,
       ttl_minutes: rules.ttl_minutes || 10,
       watch_interval_ms: rules.watch_interval_ms || 5000,
+      strict_next_owner: rules.strict_next_owner === true,
       ...(rules.verify_command ? { verify_command: rules.verify_command } : {})
     }
   };
@@ -209,7 +225,7 @@ export async function initCommand(opts) {
   writeFileSync(join(dir, 'TALK.md'), `# ${project} — Team Talk File\n\nCanonical human-readable handoff log for all agents.\n\n## How to write entries\n\nUse this exact structure:\n\n## Turn N — <agent_id> (<role>)\n- Status:\n- Decision:\n- Action:\n- Risks/Questions:\n- Next owner:\n\n---\n\n`);
   writeFileSync(join(dir, 'HUMAN_TASKS.md'), '# Human Tasks\n\n(Agents append tasks here when they need human action.)\n');
   const gitignorePath = join(dir, '.gitignore');
-  const requiredIgnores = ['.env', '.agentxchain-trigger.json', '.agentxchain-prompts/', '.agentxchain-workspaces/'];
+  const requiredIgnores = ['.env', '.agentxchain-trigger.json', '.agentxchain-prompts/', '.agentxchain-workspaces/', '.agentxchain-watch.pid', '.agentxchain-autonudge.state'];
   if (!existsSync(gitignorePath)) {
     writeFileSync(gitignorePath, requiredIgnores.join('\n') + '\n');
   } else {
@@ -230,10 +246,13 @@ export async function initCommand(opts) {
 
   writeFileSync(join(dir, '.planning', 'REQUIREMENTS.md'), `# Requirements — ${project}\n\n## v1 (MVP)\n\n(PM fills this: numbered list of requirements. Each requirement has one-sentence acceptance criteria.)\n\n| # | Requirement | Acceptance criteria | Phase | Status |\n|---|-------------|-------------------|-------|--------|\n| 1 | | | | Pending |\n\n## v2 (Future)\n\n(Out of scope for MVP. Captured here so they don't creep in.)\n\n## Out of scope\n\n(Explicitly not building.)\n`);
 
-  writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${project}\n\n## Phases\n\n| Phase | Description | Status | Requirements |\n|-------|-------------|--------|-------------|\n| 1 | Discovery + setup | In progress | — |\n\n(PM updates this as phases are planned and completed.)\n`);
+  writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${project}\n\n## Waves\n\n| Wave | Goal | Status |\n|------|------|--------|\n| Wave 1 | Discovery, planning, and phase setup | In progress |\n\n## Phases\n\n| Phase | Description | Status | Requirements |\n|-------|-------------|--------|-------------|\n| 1 | Discovery + setup | In progress | — |\n\n(PM updates this as phases are planned and completed.)\n`);
   writeFileSync(join(dir, '.planning', 'PM_SIGNOFF.md'), `# PM Signoff — ${project}\n\nApproved: NO\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`);
 
   // QA structure
+  mkdirSync(join(dir, '.planning', 'phases', 'phase-1'), { recursive: true });
+  writeFileSync(join(dir, '.planning', 'phases', 'phase-1', 'PLAN.md'), `# Phase 1 Plan — ${project}\n\n## Goal\n\nAlign scope, requirements, and initial implementation plan.\n\n## Deliverables\n\n- PM signoff\n- Initial requirements and roadmap\n- First implementation slice\n`);
+  writeFileSync(join(dir, '.planning', 'phases', 'phase-1', 'TESTS.md'), `# Phase 1 Tests — ${project}\n\n## Planned checks\n\n- Kickoff validation passes\n- Requirements have acceptance criteria\n- First implementation slice has an executable verification path\n`);
   writeFileSync(join(dir, '.planning', 'qa', 'TEST-COVERAGE.md'), `# Test Coverage — ${project}\n\n## Coverage Map\n\n| Feature / Area | Unit tests | Integration tests | E2E tests | Manual QA | UX audit | Status |\n|---------------|-----------|------------------|----------|----------|---------|--------|\n| (QA fills this as testing progresses) | | | | | | |\n\n## Coverage gaps\n\n(Areas with no tests or insufficient coverage.)\n`);
 
   writeFileSync(join(dir, '.planning', 'qa', 'REGRESSION-LOG.md'), `# Regression Log — ${project}\n\nBugs that were found and fixed. Each entry has a regression test to prevent recurrence.\n\n| Bug ID | Description | Found turn | Fixed turn | Regression test | Status |\n|--------|-------------|-----------|-----------|----------------|--------|\n| (QA adds entries as bugs are found and fixed) | | | | | |\n`);

package/src/commands/rebind.js

@@ -0,0 +1,77 @@
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+import { loadConfig } from '../lib/config.js';
+import { generatePollingPrompt } from '../lib/seed-prompt-polling.js';
+
+export async function rebindCommand(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 agentEntries = Object.entries(config.agents || {});
+  if (agentEntries.length === 0) {
+    console.log(chalk.red('No agents configured in agentxchain.json.'));
+    process.exit(1);
+  }
+
+  const selected = opts.agent
+    ? agentEntries.filter(([id]) => id === opts.agent)
+    : agentEntries;
+
+  if (opts.agent && selected.length === 0) {
+    console.log(chalk.red(`Agent "${opts.agent}" not found in agentxchain.json.`));
+    process.exit(1);
+  }
+
+  const promptDir = join(root, '.agentxchain-prompts');
+  const workspacesDir = join(root, '.agentxchain-workspaces');
+  mkdirSync(promptDir, { recursive: true });
+  mkdirSync(workspacesDir, { recursive: true });
+
+  for (const [id, def] of selected) {
+    const prompt = generatePollingPrompt(id, def, config, root);
+    writeFileSync(join(promptDir, `${id}.prompt.md`), prompt);
+
+    const wsPath = join(workspacesDir, `${id}.code-workspace`);
+    const workspaceJson = {
+      folders: [{ path: root }],
+      settings: { 'agentxchain.agentId': id }
+    };
+    writeFileSync(wsPath, JSON.stringify(workspaceJson, null, 2) + '\n');
+
+    if (opts.open) {
+      openCursorWindow(wsPath);
+    }
+  }
+
+  const statePath = join(root, '.agentxchain-autonudge.state');
+  if (existsSync(statePath)) {
+    rmSync(statePath, { force: true });
+  }
+
+  console.log('');
+  console.log(chalk.green(`  ✓ Rebound ${selected.length} agent session(s).`));
+  console.log(chalk.dim(`  Prompts:     ${join('.agentxchain-prompts', opts.agent ? `${opts.agent}.prompt.md` : '')}`));
+  console.log(chalk.dim(`  Workspaces:  ${join('.agentxchain-workspaces', opts.agent ? `${opts.agent}.code-workspace` : '')}`));
+  console.log(chalk.dim('  Auto-nudge dispatch state reset.'));
+  if (!opts.open) {
+    console.log(chalk.dim('  Use `agentxchain rebind --open` to reopen agent windows now.'));
+  }
+  console.log('');
+}
+
+function openCursorWindow(targetPath) {
+  try {
+    if (process.platform === 'darwin') {
+      execSync(`open -na "Cursor" --args "${targetPath}"`, { stdio: 'ignore' });
+      return;
+    }
+    execSync(`cursor --new-window "${targetPath}"`, { stdio: 'ignore' });
+  } catch {}
+}
+

package/src/commands/stop.js

@@ -2,8 +2,10 @@ import { readFileSync, existsSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig } from '../lib/config.js';
+import { getWatchPid } from './watch.js';
 
 const SESSION_FILE = '.agentxchain-session.json';
+const WATCH_PID_FILE = '.agentxchain-watch.pid';
 
 export async function stopCommand() {
   const result = loadConfig();
@@ -11,47 +13,77 @@ export async function stopCommand() {
 
   const { root } = result;
   const sessionPath = join(root, SESSION_FILE);
+  const watchPidPath = join(root, WATCH_PID_FILE);
+  const watchPid = getWatchPid(root);
+  let didStopAnything = false;
 
-  if (!existsSync(sessionPath)) {
-    console.log(chalk.yellow('  No active session found.'));
-    console.log(chalk.dim('  If agents are running in VS Code / Cursor, close their chat sessions manually.'));
-    return;
+  if (watchPid) {
+    try {
+      process.kill(watchPid, 'SIGTERM');
+      didStopAnything = true;
+      console.log('');
+      console.log(chalk.green(`  ✓ Stopped watch process (PID: ${watchPid})`));
+      console.log('');
+    } catch (err) {
+      if (err.code === 'ESRCH') {
+        if (existsSync(watchPidPath)) {
+          try { unlinkSync(watchPidPath); } catch {}
+        }
+      } else {
+        console.log(chalk.red(`  ✗ Could not stop watch process (PID: ${watchPid}): ${err.message}`));
+      }
+    }
+  } else if (existsSync(watchPidPath)) {
+    // Stale PID file from an unexpected shutdown.
+    try {
+      unlinkSync(watchPidPath);
+      console.log(chalk.dim('  Removed stale watch PID file.'));
+    } catch {}
   }
 
-  let session;
-  try {
-    session = JSON.parse(readFileSync(sessionPath, 'utf8'));
-  } catch {
-    console.log(chalk.yellow('  Could not read session file.'));
-    return;
-  }
+  if (existsSync(sessionPath)) {
+    let session;
+    try {
+      session = JSON.parse(readFileSync(sessionPath, 'utf8'));
+    } catch {
+      console.log(chalk.yellow('  Could not read session file.'));
+      return;
+    }
+
+    console.log('');
+    console.log(chalk.bold(`  Stopping ${session.launched?.length || 0} agents (${session.ide || 'unknown'})`));
+    console.log('');
 
-  console.log('');
-  console.log(chalk.bold(`  Stopping ${session.launched?.length || 0} agents (${session.ide || 'unknown'})`));
-  console.log('');
-
-  if (session.ide === 'claude-code') {
-    for (const agent of (session.launched || [])) {
-      if (agent.pid) {
-        try {
-          process.kill(agent.pid, 'SIGTERM');
-          console.log(chalk.green(`  ✓ Sent SIGTERM to ${agent.id} (PID: ${agent.pid})`));
-        } catch (err) {
-          if (err.code === 'ESRCH') {
-            console.log(chalk.dim(`  ${agent.id} (PID: ${agent.pid}) — already stopped`));
-          } else {
-            console.log(chalk.red(`  ✗ ${agent.id}: ${err.message}`));
+    if (session.ide === 'claude-code') {
+      for (const agent of (session.launched || [])) {
+        if (agent.pid) {
+          try {
+            process.kill(agent.pid, 'SIGTERM');
+            didStopAnything = true;
+            console.log(chalk.green(`  ✓ Sent SIGTERM to ${agent.id} (PID: ${agent.pid})`));
+          } catch (err) {
+            if (err.code === 'ESRCH') {
+              console.log(chalk.dim(`  ${agent.id} (PID: ${agent.pid}) — already stopped`));
+            } else {
+              console.log(chalk.red(`  ✗ ${agent.id}: ${err.message}`));
+            }
           }
         }
       }
+    } else {
+      console.log(chalk.dim('  For VS Code / Cursor agents, close the chat sessions manually.'));
     }
-  } else {
-    console.log(chalk.dim('  For VS Code / Cursor agents, close the chat sessions manually.'));
+
+    unlinkSync(sessionPath);
+    console.log('');
+    console.log(chalk.dim('  Session file removed.'));
+    console.log(chalk.green('  Done.'));
+    console.log('');
+    return;
   }
 
-  unlinkSync(sessionPath);
-  console.log('');
-  console.log(chalk.dim('  Session file removed.'));
-  console.log(chalk.green('  Done.'));
-  console.log('');
+  if (!didStopAnything) {
+    console.log(chalk.yellow('  No active session found.'));
+    console.log(chalk.dim('  If agents are running in VS Code / Cursor, close their chat sessions manually.'));
+  }
 }

package/src/commands/update.js

@@ -4,6 +4,19 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import chalk from 'chalk';
 
+function printGlobalInstallFallbacks() {
+  console.log(chalk.dim('  If global install failed with permission errors (EACCES):'));
+  console.log(`    ${chalk.bold('sudo npm install -g agentxchain@latest')}  ${chalk.dim('(macOS/Linux)')}`);
+  console.log(`    ${chalk.bold('npm config get prefix')}  ${chalk.dim('— fix ownership of that directory, or use a user prefix:')}`);
+  console.log(`    ${chalk.bold('mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global')}`);
+  console.log(`    ${chalk.dim('(add ~/.npm-global/bin to PATH)')}`);
+  console.log(chalk.dim('  Or run without global install:'));
+  console.log(`    ${chalk.bold('npx agentxchain@latest <command>')}`);
+  console.log('');
+  console.log(chalk.dim('  Node: use 18.17+ or 20.5+ to avoid engine warnings from dependencies.'));
+  console.log('');
+}
+
 export async function updateCommand() {
   const __dirname = dirname(fileURLToPath(import.meta.url));
   const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'));
@@ -24,18 +37,26 @@ export async function updateCommand() {
 
     console.log(`  ${chalk.dim('Latest version:')}  ${chalk.cyan(latest)}`);
     console.log('');
-    console.log(`  Updating...`);
+    console.log('  Updating...');
 
-    execSync('npm install -g agentxchain@latest', { stdio: 'inherit' });
+    try {
+      execSync('npm install -g agentxchain@latest', { stdio: 'inherit' });
+    } catch {
+      console.log('');
+      console.log(chalk.yellow('  Global install failed. Common fixes:'));
+      printGlobalInstallFallbacks();
+      return;
+    }
 
     console.log('');
     console.log(chalk.green(`  ✓ Updated to ${latest}`));
     console.log('');
   } catch (err) {
     console.log('');
-    console.log(chalk.yellow('  Could not auto-update. Run manually:'));
+    console.log(chalk.yellow('  Could not check or install the latest version.'));
     console.log(`    ${chalk.bold('npm install -g agentxchain@latest')}`);
     console.log('');
+    printGlobalInstallFallbacks();
     console.log(chalk.dim(`  Error: ${err.message}`));
     console.log('');
   }