agentxchain 0.8.7 → 0.8.8

package/README.md

@@ -19,8 +19,8 @@ npx agentxchain init
 ### Happy path: net-new project
 
 ```bash
-agentxchain init
-cd my-project
+npx agentxchain init
+cd my-agentxchain-project   # default with init -y, or your chosen folder name
 agentxchain kickoff
 ```
 
@@ -52,8 +52,9 @@ Agents are now required to maintain `TALK.md` as the human-readable handoff log
 | `doctor` | Validate local setup (tools, trigger flow, accessibility checks) |
 | `claim` | Human takes control (agents stop claiming) |
 | `release` | Hand lock back to agents |
-| `stop` | Terminate running Claude Code agent sessions |
-| `watch` | Optional: TTL safety net + status logging |
+| `stop` | Stop watch daemon, end Claude Code sessions; Cursor/VS Code chats close manually |
+| `branch` | Show/set Cursor branch override for launches |
+| `watch` | Referee loop: validates turns, writes next trigger, and force-releases stale locks |
 | `config` | View/edit config, add/remove agents, change rules |
 | `rebind` | Rebuild Cursor workspace/prompt bindings for agents |
 | `update` | Self-update CLI from npm |
@@ -66,6 +67,7 @@ agentxchain status
 agentxchain start
 agentxchain kickoff
 agentxchain stop
+agentxchain branch
 agentxchain config
 agentxchain rebind
 agentxchain generate
@@ -111,37 +113,22 @@ agentxchain rebind --agent pm       # regenerate one agent binding only
 agentxchain claim --agent pm        # guarded claim as agent turn owner
 agentxchain release --agent pm      # guarded release as agent turn owner
 agentxchain release --force         # force-release non-human holder lock
+agentxchain config --set "rules.strict_next_owner true"  # TALK-only next owner (no cyclic fallback)
 ```
 
 ## macOS auto-nudge (AppleScript)
 
-If you want the next agent chat to be nudged automatically when turn changes, use the built-in AppleScript helper.
-
-1) Keep watcher running in your project:
+**Recommended:** `agentxchain supervise --autonudge` (starts `watch` + auto-nudge together). Requires macOS, `jq`, and Accessibility for Terminal + Cursor.
 
 ```bash
-agentxchain watch
-# or use the combined command:
 agentxchain supervise --autonudge
+agentxchain supervise --autonudge --send   # paste + Enter
 ```
 
-2) In another terminal (from `cli/`), start auto-nudge:
-
-```bash
-bash scripts/run-autonudge.sh --project "/absolute/path/to/your-project"
-```
-
-By default this is **paste-only** (safe mode): it opens chat and pastes the nudge message, but does not press Enter.
-
-3) Enable auto-send once confirmed:
-
-```bash
-bash scripts/run-autonudge.sh --project "/absolute/path/to/your-project" --send
-```
-
-Stop it anytime:
+**Advanced (debugging):** from a checkout of `cli/`, run the script alone while `watch` is already running:
 
 ```bash
+bash scripts/run-autonudge.sh --project "/absolute/path/to/your-project" [--send]
 bash scripts/stop-autonudge.sh
 ```
 
@@ -166,7 +153,7 @@ Notes:
 ### VS Code mode
 
 1. `agentxchain init` generates `.github/agents/*.agent.md` (VS Code custom agents) and `.github/hooks/` (lifecycle hooks)
-2. VS Code auto-discovers agents in the Chat dropdown
+2. VS Code discovers custom agents in Chat when using **GitHub Copilot** agents (see Microsoft docs)
 3. The `Stop` hook acts as referee — hands off to next agent automatically
 
 ### Turn ownership
@@ -189,14 +176,12 @@ Agent turns are handoff-driven:
 
 ## VS Code extension (optional)
 
-For a richer UI in VS Code:
+The VSIX is not committed to the repo. Build/package from `cli/vscode-extension/` (see that folder’s README or `vsce package`), then:
 
 ```bash
-code --install-extension cli/vscode-extension/agentxchain-0.1.0.vsix
+code --install-extension /path/to/agentxchain-*.vsix
 ```
 
-Adds: status bar (lock holder, turn, phase), sidebar dashboard, command palette integration.
-
 ## Publish updates (maintainers)
 
 ```bash

package/bin/agentxchain.js

@@ -1,9 +1,52 @@
 #!/usr/bin/env node
 
-import { readFileSync } from 'fs';
-import { join, dirname } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname, parse as pathParse, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
+
+// Load .env from AgentXchain project root when available, then cwd as fallback.
+(function loadDotenv() {
+  const cwd = process.cwd();
+  const projectRoot = findNearestProjectRoot(cwd);
+  const envPaths = [];
+
+  if (projectRoot) {
+    envPaths.push(join(projectRoot, '.env'));
+  }
+  if (!projectRoot || projectRoot !== cwd) {
+    envPaths.push(join(cwd, '.env'));
+  }
+
+  for (const envPath of envPaths) {
+    if (!existsSync(envPath)) continue;
+    try {
+      const content = readFileSync(envPath, 'utf8');
+      for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx === -1) continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        let val = trimmed.slice(eqIdx + 1).trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          val = val.slice(1, -1);
+        }
+        if (!process.env[key]) process.env[key] = val;
+      }
+    } catch {}
+  }
+})();
+
+function findNearestProjectRoot(startDir) {
+  let dir = resolve(startDir);
+  const { root: fsRoot } = pathParse(dir);
+  while (true) {
+    if (existsSync(join(dir, 'agentxchain.json'))) return dir;
+    if (dir === fsRoot) return null;
+    dir = join(dir, '..');
+  }
+}
 import { initCommand } from '../src/commands/init.js';
 import { statusCommand } from '../src/commands/status.js';
 import { startCommand } from '../src/commands/start.js';
@@ -18,6 +61,7 @@ import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
 import { rebindCommand } from '../src/commands/rebind.js';
+import { branchCommand } from '../src/commands/branch.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -61,7 +105,7 @@ program
 
 program
   .command('stop')
-  .description('Stop all running agent sessions')
+  .description('Stop watch daemon and Claude Code sessions; close Cursor/VS Code chats manually')
   .action(stopCommand);
 
 program
@@ -73,6 +117,13 @@ program
   .option('-j, --json', 'Output config as JSON')
   .action(configCommand);
 
+program
+  .command('branch [name]')
+  .description('Show or set the Cursor branch used for launches')
+  .option('--use-current', 'Set override to the current local git branch')
+  .option('--unset', 'Remove override and follow the active git branch automatically')
+  .action(branchCommand);
+
 program
   .command('generate')
   .description('Regenerate VS Code agent files (.agent.md, hooks) from agentxchain.json')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   ],
   "scripts": {
     "dev": "node bin/agentxchain.js",
+    "test": "node --test test/*.test.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",
     "publish:npm": "bash scripts/publish-npm.sh"
@@ -43,6 +44,6 @@
     "ora": "^8.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=18.17.0 || >=20.5.0"
   }
 }

package/scripts/agentxchain-autonudge.applescript

@@ -59,8 +59,31 @@ on nudgeAgent(agentId, turnNum, dispatchKey)
   set nudgeText to "Hey " & agentId & ", it is your turn now (turn " & turnNum & "). Read lock.json, claim the lock, check state.md + history.jsonl + planning docs, do your work, and release lock."
   set the clipboard to nudgeText
 
+  tell application "System Events"
+    if not (exists process "Cursor") then
+      if lastFailedDispatch is not dispatchKey then
+        do shell script "osascript -e " & quoted form of ("display notification \"Cursor is not running.\" with title \"AgentXchain\"")
+        set lastFailedDispatch to dispatchKey
+      end if
+      return false
+    end if
+  end tell
+
   tell application "Cursor" to activate
-  delay 0.5
+  delay 0.6
+
+  -- Verify Cursor is actually frontmost before sending keystrokes
+  tell application "System Events"
+    set frontApp to name of first application process whose frontmost is true
+    if frontApp is not "Cursor" then
+      if lastFailedDispatch is not dispatchKey then
+        do shell script "osascript -e " & quoted form of ("display notification \"Cursor lost focus, skipping nudge for " & agentId & ".\" with title \"AgentXchain\"")
+        set lastFailedDispatch to dispatchKey
+      end if
+      return false
+    end if
+  end tell
+
   set focusedOk to my focusAgentWindow(agentId)
   if focusedOk is false then
     if lastFailedDispatch is not dispatchKey then
@@ -69,18 +92,22 @@ on nudgeAgent(agentId, turnNum, dispatchKey)
     end if
     return false
   end if
-  delay 0.2
+  delay 0.3
 
+  -- Re-verify focus before keystrokes
   tell application "System Events"
-    if not (exists process "Cursor") then return
+    set frontApp to name of first application process whose frontmost is true
+    if frontApp is not "Cursor" then
+      return false
+    end if
 
     tell process "Cursor"
       set frontmost to true
       keystroke "l" using {command down}
-      delay 0.2
+      delay 0.3
       keystroke "v" using {command down}
       if autoSend then
-        delay 0.15
+        delay 0.2
         key code 36
       end if
     end tell

package/scripts/run-autonudge.sh

@@ -104,7 +104,7 @@ echo "Mode:      $( [[ "${AUTO_SEND}" == "true" ]] && echo "auto-send" || echo "
 echo "Interval:  ${INTERVAL_SECONDS}s"
 echo ""
 echo "Requirements:"
-echo "- Keep 'agentxchain watch' running in another terminal."
+echo "- Watch must be running (e.g. 'agentxchain supervise --autonudge' starts it in the same supervisor, or run 'agentxchain watch' in another terminal)."
 echo "- Grant Accessibility permission to Terminal and Cursor."
 echo ""
 

package/src/adapters/claude-code.js

@@ -1,8 +1,9 @@
 import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { generateSeedPrompt } from '../lib/seed-prompt.js';
-import { writeFileSync } from 'fs';
 import { join } from 'path';
+import { safeWriteJson } from '../lib/safe-write.js';
+import { filterAgents } from '../lib/filter-agents.js';
 
 export async function launchClaudeCodeAgents(config, root, opts) {
   const agents = filterAgents(config, opts.agent);
@@ -28,22 +29,14 @@ export async function launchClaudeCodeAgents(config, root, opts) {
   }
 
   if (launched.length > 0) {
-    const sessionFile = JSON.stringify({ launched, started_at: new Date().toISOString(), ide: 'claude-code' }, null, 2);
-    writeFileSync(join(root, '.agentxchain-session.json'), sessionFile + '\n');
+    safeWriteJson(join(root, '.agentxchain-session.json'), {
+      launched,
+      started_at: new Date().toISOString(),
+      ide: 'claude-code'
+    });
     console.log('');
     console.log(chalk.dim(`  Session saved to .agentxchain-session.json`));
   }
 
   return launched;
 }
-
-function filterAgents(config, specificId) {
-  if (specificId) {
-    if (!config.agents[specificId]) {
-      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
-      process.exit(1);
-    }
-    return { [specificId]: config.agents[specificId] };
-  }
-  return config.agents;
-}

package/src/adapters/cursor-local.js

@@ -4,6 +4,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { generatePollingPrompt } from '../lib/seed-prompt-polling.js';
+import { filterAgents } from '../lib/filter-agents.js';
 
 export async function launchCursorLocal(config, root, opts) {
   const agents = filterAgents(config, opts.agent);
@@ -50,13 +51,22 @@ export async function launchCursorLocal(config, root, opts) {
     console.log(chalk.cyan(`  ─── Agent ${i + 1}/${total}: ${chalk.bold(id)} — ${agent.name} ───`));
     console.log('');
 
-    copyToClipboard(prompt);
-    console.log(chalk.green(`  ✓ Prompt copied to clipboard.`));
+    const copied = copyToClipboard(prompt);
+    if (copied) {
+      console.log(chalk.green('  ✓ Prompt copied to clipboard.'));
+    } else {
+      console.log(chalk.yellow('  ! Clipboard copy failed. Use the saved prompt file manually.'));
+    }
     console.log(chalk.dim(`    Saved to: .agentxchain-prompts/${id}.prompt.md`));
 
     // Open a separate Cursor window using the symlinked path
-    openCursorWindow(agentWorkspace);
-    console.log(chalk.dim(`    Cursor window opened for ${id}.`));
+    const opened = openCursorWindow(agentWorkspace);
+    if (opened) {
+      console.log(chalk.dim(`    Cursor window opened for ${id}.`));
+    } else {
+      console.log(chalk.yellow(`    Could not open Cursor window automatically for ${id}.`));
+      console.log(chalk.dim(`    Open manually: cursor --new-window "${agentWorkspace}"`));
+    }
 
     console.log('');
     console.log(`  ${chalk.bold('In the new Cursor window:')}`);
@@ -108,17 +118,6 @@ export async function launchCursorLocal(config, root, opts) {
   console.log('');
 }
 
-function filterAgents(config, specificId) {
-  if (specificId) {
-    if (!config.agents[specificId]) {
-      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
-      process.exit(1);
-    }
-    return { [specificId]: config.agents[specificId] };
-  }
-  return config.agents;
-}
-
 function copyToClipboard(text) {
   try {
     if (process.platform === 'darwin') {
@@ -137,10 +136,12 @@ function openCursorWindow(folderPath) {
   try {
     if (process.platform === 'darwin') {
       execSync(`open -na "Cursor" --args "${folderPath}"`, { stdio: 'ignore' });
-      return;
+      return true;
     }
     execSync(`cursor --new-window "${folderPath}"`, { stdio: 'ignore' });
+    return true;
   } catch {}
+  return false;
 }
 
 function isPmLike(agentId, agentDef) {

package/src/commands/branch.js

@@ -1,7 +1,7 @@
-import { writeFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, CONFIG_FILE } from '../lib/config.js';
+import { safeWriteJson } from '../lib/safe-write.js';
 import { getCurrentBranch } from '../lib/repo.js';
 
 export async function branchCommand(name, opts) {
@@ -94,5 +94,5 @@ function setBranchOverride(config, configPath, branch) {
 }
 
 function saveConfig(configPath, config) {
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  safeWriteJson(configPath, config);
 }

package/src/commands/claim.js

@@ -1,8 +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 { resolveNextAgent } from '../lib/next-owner.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();
@@ -40,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('');
@@ -76,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,
@@ -83,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('');
 }
 
@@ -108,11 +125,25 @@ function claimAsAgent({ opts, root, config, lock }) {
   }
 
   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,
@@ -120,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})`));
 }
 
@@ -135,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,
@@ -142,12 +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(root, lock, config) {
-  return resolveNextAgent(root, config, lock).next;
+  return resolveExpectedClaimer(root, config, lock).next;
 }
 
 function clearBlockedState(root) {
@@ -157,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`)' };
   }