agentxchain 0.8.5 → 0.8.7

package/README.md

@@ -16,16 +16,25 @@ npx agentxchain init
 
 ## Quick start
 
+### Happy path: net-new project
+
 ```bash
-# 1. Create a project (interactive template selection)
 agentxchain init
+cd my-project
+agentxchain kickoff
+```
+
+### Happy path: existing project
 
-# 2. Run guided PM-first kickoff wizard
-cd my-project/
+Run these commands from inside your existing project folder:
+
+```bash
+agentxchain doctor
+agentxchain generate
 agentxchain kickoff
 ```
 
-Each agent runs in its own Cursor window with a self-polling loop. Agents check `lock.json` every 60 seconds, claim when it's their turn, do their work, release, and go back to waiting. `supervise --autonudge` handles watch + nudging automatically.
+Each agent runs in its own Cursor window for a single turn at a time. The referee loop (`watch` / `supervise --autonudge`) determines the next agent and wakes that specific session.
 
 Agents are now required to maintain `TALK.md` as the human-readable handoff log each turn.
 
@@ -46,8 +55,29 @@ Agents are now required to maintain `TALK.md` as the human-readable handoff log
 | `stop` | Terminate running Claude Code agent sessions |
 | `watch` | Optional: TTL safety net + status logging |
 | `config` | View/edit config, add/remove agents, change rules |
+| `rebind` | Rebuild Cursor workspace/prompt bindings for agents |
 | `update` | Self-update CLI from npm |
 
+### Full command list
+
+```bash
+agentxchain init
+agentxchain status
+agentxchain start
+agentxchain kickoff
+agentxchain stop
+agentxchain config
+agentxchain rebind
+agentxchain generate
+agentxchain watch
+agentxchain supervise
+agentxchain claim
+agentxchain release
+agentxchain update
+agentxchain doctor
+agentxchain validate
+```
+
 ### IDE options
 
 ```bash
@@ -62,15 +92,24 @@ agentxchain start --ide claude-code # Claude Code — spawns CLI processes
 agentxchain kickoff                # guided first-run PM-first workflow
 agentxchain kickoff --ide vscode   # guided flow for VS Code mode
 agentxchain kickoff --send         # with Cursor auto-nudge auto-send enabled
+agentxchain kickoff --interval 2   # nudge poll interval override
+agentxchain kickoff --no-autonudge # skip auto-nudge prompt
 
 agentxchain start --agent pm        # launch only one specific agent
 agentxchain start --remaining       # launch all agents except PM (PM-first flow)
 agentxchain start --dry-run         # preview agents without launching
 agentxchain validate --mode kickoff # required before --remaining
 agentxchain validate --mode turn --agent pm
+agentxchain validate --json         # machine-readable validation output
 agentxchain watch --daemon          # run watch in background
 agentxchain supervise --autonudge   # run watch + AppleScript nudge loop
 agentxchain supervise --autonudge --send   # auto-press Enter after paste
+agentxchain supervise --interval 2  # set auto-nudge poll interval
+agentxchain rebind                  # regenerate agent prompt/workspace bindings
+agentxchain rebind --open           # regenerate and reopen all Cursor agent windows
+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
 ```
 
@@ -120,8 +159,8 @@ Notes:
 1. `agentxchain kickoff` launches PM first for human-product alignment
 2. Each window gets a unique prompt copied to clipboard
 3. Kickoff validates PM signoff and launches remaining agents
-4. Agent prompts include a self-polling loop: read `lock.json` → check if it's my turn → claim → work → release → sleep 60s → repeat
-5. Agents know their rotation order from `agentxchain.json` and only claim when the previous agent released
+4. Agent prompts are single-turn: claim → work → validate → release → stop
+5. Agents use the latest `Next owner:` in `TALK.md` to pick who goes next (fallback: config order)
 6. Human can `claim` to pause and `release` to resume anytime
 
 ### VS Code mode
@@ -130,18 +169,17 @@ Notes:
 2. VS Code auto-discovers agents in the Chat dropdown
 3. The `Stop` hook acts as referee — hands off to next agent automatically
 
-### Turn rotation
+### Turn ownership
 
-Agents follow a round-robin order defined in `agentxchain.json`:
-- PM waits for: lock free + last released by `human`, `null`, or last agent in rotation
-- Dev waits for: lock free + last released by `pm`
-- QA waits for: lock free + last released by `dev`
-- And so on...
+Agent turns are handoff-driven:
+- Each turn appends a `Next owner:` in `TALK.md` with a valid agent id
+- `watch`/`supervise` dispatches the next trigger from that handoff
+- `claim --agent <id>` enforces that expected owner (with guarded fallback)
 
 ## Key features
 
 - **One window per agent** — each agent has its own Cursor window and chat session
-- **Self-polling coordination** — agents check `lock.json` every 60s, no external process needed
+- **Referee-driven coordination** — `watch`/`supervise` wakes the next correct agent each turn
 - **Works in Cursor, VS Code, Claude Code** — adapters for each IDE
 - **User-defined teams** — any number of agents, any roles
 - **No API keys or cloud required** — everything runs locally

package/bin/agentxchain.js

@@ -17,6 +17,7 @@ import { doctorCommand } from '../src/commands/doctor.js';
 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';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -91,15 +92,24 @@ program
   .option('--interval <seconds>', 'Auto-nudge poll interval in seconds', '3')
   .action(superviseCommand);
 
+program
+  .command('rebind')
+  .description('Rebuild Cursor prompt/workspace bindings for agents')
+  .option('--agent <id>', 'Rebind a single agent only')
+  .option('--open', 'Reopen Cursor windows after rebinding')
+  .action(rebindCommand);
+
 program
   .command('claim')
   .description('Claim the lock as a human (take control)')
+  .option('--agent <id>', 'Claim lock as a specific agent (guarded by turn order)')
   .option('--force', 'Force-claim even if an agent holds the lock')
   .action(claimCommand);
 
 program
   .command('release')
   .description('Release the lock (hand back to agents)')
+  .option('--agent <id>', 'Release lock as a specific agent')
   .option('--force', 'Force release even if a non-human holder has the lock')
   .action(releaseCommand);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {

package/scripts/agentxchain-autonudge.applescript

@@ -1,6 +1,7 @@
 property projectRoot : ""
 property pollSeconds : 3
 property autoSend : false
+property lastFailedDispatch : ""
 
 on run argv
   if (count of argv) < 1 then
@@ -41,8 +42,10 @@ on run argv
           set lastKey to do shell script "test -f " & quoted form of statePath & " && cat " & quoted form of statePath & " || echo ''"
 
           if dispatchKey is not lastKey then
-            my nudgeAgent(agentId, turnNum)
-            do shell script "printf %s " & quoted form of dispatchKey & " > " & quoted form of statePath
+            set nudgedOk to my nudgeAgent(agentId, turnNum, dispatchKey)
+            if nudgedOk then
+              do shell script "printf %s " & quoted form of dispatchKey & " > " & quoted form of statePath
+            end if
           end if
         end if
       end if
@@ -52,7 +55,7 @@ on run argv
   end repeat
 end run
 
-on nudgeAgent(agentId, turnNum)
+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
 
@@ -60,8 +63,11 @@ on nudgeAgent(agentId, turnNum)
   delay 0.5
   set focusedOk to my focusAgentWindow(agentId)
   if focusedOk is false then
-    do shell script "osascript -e " & quoted form of ("display notification \"Could not identify a unique window for " & agentId & ".\" with title \"AgentXchain\"")
-    return
+    if lastFailedDispatch is not dispatchKey then
+      do shell script "osascript -e " & quoted form of ("display notification \"Could not identify a unique window for " & agentId & ".\" with title \"AgentXchain\"")
+      set lastFailedDispatch to dispatchKey
+    end if
+    return false
   end if
   delay 0.2
 
@@ -80,7 +86,9 @@ on nudgeAgent(agentId, turnNum)
     end tell
   end tell
 
+  set lastFailedDispatch to ""
   do shell script "osascript -e " & quoted form of ("display notification \"Nudged " & agentId & " for turn " & turnNum & "\" with title \"AgentXchain\"")
+  return true
 end nudgeAgent
 
 on focusAgentWindow(agentId)
@@ -117,6 +125,10 @@ end focusAgentWindow
 
 on isStrongWindowMatch(windowName, agentId)
   set tokenA to ".agentxchain-workspaces/" & agentId
+  set tokenB to ".agentxchain-workspaces\\" & agentId
+  set tokenC to agentId & ".code-workspace"
   if windowName contains tokenA then return true
+  if windowName contains tokenB then return true
+  if windowName contains tokenC then return true
   return false
 end isStrongWindowMatch

package/src/adapters/cursor-local.js

@@ -1,5 +1,5 @@
 import { execSync } from 'child_process';
-import { writeFileSync, mkdirSync, existsSync, symlinkSync, lstatSync, unlinkSync } from 'fs';
+import { writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
@@ -29,7 +29,7 @@ export async function launchCursorLocal(config, root, opts) {
     writeFileSync(join(promptDir, `${id}.prompt.md`), prompt);
   }
 
-  // Create per-agent symlinked workspace folders so Cursor opens separate windows
+  // Create per-agent workspace files so each Cursor window has a unique identity
   const workspacesDir = join(root, '.agentxchain-workspaces');
   mkdirSync(workspacesDir, { recursive: true });
 
@@ -39,17 +39,13 @@ export async function launchCursorLocal(config, root, opts) {
       ? generateKickoffPrompt(id, agent, config, root)
       : generatePollingPrompt(id, agent, config, root);
 
-    // Create symlink: .agentxchain-workspaces/<id> -> project root
-    const agentWorkspace = join(workspacesDir, id);
-    try {
-      if (existsSync(agentWorkspace)) {
-        const stat = lstatSync(agentWorkspace);
-        if (stat.isSymbolicLink()) unlinkSync(agentWorkspace);
-      }
-      if (!existsSync(agentWorkspace)) {
-        symlinkSync(root, agentWorkspace, 'dir');
-      }
-    } catch {}
+    // Create workspace file: .agentxchain-workspaces/<id>.code-workspace
+    const agentWorkspace = join(workspacesDir, `${id}.code-workspace`);
+    const workspaceJson = {
+      folders: [{ path: root }],
+      settings: { 'agentxchain.agentId': id }
+    };
+    writeFileSync(agentWorkspace, JSON.stringify(workspaceJson, null, 2) + '\n');
 
     console.log(chalk.cyan(`  ─── Agent ${i + 1}/${total}: ${chalk.bold(id)} — ${agent.name} ───`));
     console.log('');
@@ -107,7 +103,7 @@ export async function launchCursorLocal(config, root, opts) {
   console.log(`    ${chalk.bold('agentxchain watch')}    ${chalk.dim('# watcher / trigger writer')}`);
   console.log(`    ${chalk.bold('agentxchain doctor')}   ${chalk.dim('# check local setup + trigger health')}`);
   console.log('');
-  console.log(chalk.dim('  Agents self-coordinate via lock.json polling (sleep 60s between checks).'));
+  console.log(chalk.dim('  Agents run single turns. Watch/supervise wakes the correct next agent.'));
   console.log(chalk.dim('  Re-paste a prompt: cat .agentxchain-prompts/<agent>.prompt.md | pbcopy'));
   console.log('');
 }
@@ -162,31 +158,34 @@ Project root (strict boundary): "${projectRoot}"
 Work only inside this project folder. Do NOT scan unrelated local directories.
 
 Actions:
-1) Read:
+1) FIRST QUESTION TO HUMAN (mandatory before anything else):
+"Please describe your product idea in one paragraph, in as much detail as possible."
+
+2) Read:
 - .planning/PROJECT.md
 - .planning/REQUIREMENTS.md
 - .planning/ROADMAP.md
 - TALK.md
 - state.md
 - lock.json
-2) Ask the human focused product questions until scope is clear:
+3) After receiving that paragraph, summarize it in TALK.md, then ask focused follow-up questions:
 - target user
 - top pain point
 - core workflow
 - MVP boundary
 - success metric
-3) Update planning docs with concrete acceptance criteria and Get Shit Done structure:
+4) Update planning docs with concrete acceptance criteria and Get Shit Done structure:
 - .planning/ROADMAP.md must define Waves and Phases.
 - Create .planning/phases/phase-1/PLAN.md and TESTS.md.
-4) Update .planning/PM_SIGNOFF.md:
+5) Update .planning/PM_SIGNOFF.md:
 - Set "Approved: YES" only when human agrees kickoff is complete.
-5) Append kickoff summary to TALK.md with:
+6) Append kickoff summary to TALK.md with:
 - Status
 - Decision
 - Action
 - Risks/Questions
 - Next owner
-6) Do NOT start round-robin agent handoffs yet.
+7) Do NOT start round-robin agent handoffs yet.
 
 Context:
 - Project: ${config.project}

package/src/commands/claim.js

@@ -2,6 +2,7 @@ import { writeFileSync, 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';
 
 export async function claimCommand(opts) {
   const result = loadConfig();
@@ -11,6 +12,10 @@ export async function claimCommand(opts) {
   const lock = loadLock(root);
   if (!lock) { console.log(chalk.red('  lock.json not found.')); process.exit(1); }
 
+  if (opts.agent) {
+    return claimAsAgent({ opts, root, config, lock });
+  }
+
   if (lock.holder === 'human') {
     console.log('');
     console.log(chalk.yellow('  You already hold the lock.'));
@@ -52,6 +57,10 @@ export async function releaseCommand(opts) {
   const lock = loadLock(root);
   if (!lock) { console.log(chalk.red('  lock.json not found.')); process.exit(1); }
 
+  if (opts.agent) {
+    return releaseAsAgent({ opts, root, config, lock });
+  }
+
   if (!lock.holder) {
     console.log(chalk.yellow('  Lock is already free.'));
     return;
@@ -85,6 +94,62 @@ export async function releaseCommand(opts) {
   console.log('');
 }
 
+function claimAsAgent({ opts, root, config, lock }) {
+  const agentId = opts.agent;
+  if (!config.agents?.[agentId]) {
+    console.log(chalk.red(`  Agent "${agentId}" is not defined in agentxchain.json.`));
+    process.exit(1);
+  }
+
+  if (lock.holder && !opts.force) {
+    console.log(chalk.red(`  Lock is currently held by "${lock.holder}".`));
+    console.log(chalk.dim('  Use --force only for recovery scenarios.'));
+    process.exit(1);
+  }
+
+  const expected = pickNextAgent(root, lock, config);
+  if (!opts.force && expected && expected !== agentId) {
+    console.log(chalk.red(`  Out-of-turn claim blocked. Expected: ${expected}, got: ${agentId}.`));
+    process.exit(1);
+  }
+
+  const lockPath = join(root, LOCK_FILE);
+  const next = {
+    holder: agentId,
+    last_released_by: lock.last_released_by,
+    turn_number: lock.turn_number,
+    claimed_at: new Date().toISOString()
+  };
+  writeFileSync(lockPath, JSON.stringify(next, null, 2) + '\n');
+  console.log(chalk.green(`  ✓ Lock claimed by ${agentId} (turn ${next.turn_number})`));
+}
+
+function releaseAsAgent({ opts, root, config, lock }) {
+  const agentId = opts.agent;
+  if (!config.agents?.[agentId]) {
+    console.log(chalk.red(`  Agent "${agentId}" is not defined in agentxchain.json.`));
+    process.exit(1);
+  }
+  if (lock.holder !== agentId && !opts.force) {
+    console.log(chalk.red(`  Lock is held by "${lock.holder}", not "${agentId}".`));
+    process.exit(1);
+  }
+
+  const lockPath = join(root, LOCK_FILE);
+  const next = {
+    holder: null,
+    last_released_by: agentId,
+    turn_number: lock.turn_number + 1,
+    claimed_at: null
+  };
+  writeFileSync(lockPath, JSON.stringify(next, null, 2) + '\n');
+  console.log(chalk.green(`  ✓ Lock released by ${agentId} (turn ${next.turn_number})`));
+}
+
+function pickNextAgent(root, lock, config) {
+  return resolveNextAgent(root, config, lock).next;
+}
+
 function clearBlockedState(root) {
   const statePath = join(root, 'state.json');
   if (!existsSync(statePath)) return;

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/watch.js

@@ -6,6 +6,7 @@ import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
 import { notifyHuman as sendNotification } from '../lib/notify.js';
 import { validateProject } from '../lib/validation.js';
+import { resolveNextAgent } from '../lib/next-owner.js';
 
 export async function watchCommand(opts) {
   if (opts.daemon && process.env.AGENTXCHAIN_WATCH_DAEMON !== '1') {
@@ -50,6 +51,17 @@ export async function watchCommand(opts) {
 
       const stateKey = `${lock.holder}:${lock.turn_number}`;
 
+      if (lock.holder && lock.holder !== 'human') {
+        const expected = pickNextAgent(root, lock, config);
+        if (!isValidClaimer(root, lock, config)) {
+          log('warn', `Illegal claim detected: holder=${lock.holder}, expected=${expected}. Handing lock to HUMAN.`);
+          blockOnIllegalClaim(root, lock, config, expected);
+          sendNotification(`Illegal claim detected (${lock.holder}). Human intervention required.`);
+          lastState = null;
+          return;
+        }
+      }
+
       if (lock.holder && lock.holder !== 'human' && lock.claimed_at) {
         const elapsed = Date.now() - new Date(lock.claimed_at).getTime();
         const ttlMs = ttlMinutes * 60 * 1000;
@@ -97,7 +109,7 @@ export async function watchCommand(opts) {
           }
         }
 
-        const next = pickNextAgent(lock, config);
+        const next = pickNextAgent(root, lock, config);
         log('free', `Lock free (released by ${lock.last_released_by || 'none'}). Next: ${chalk.bold(next)}.`);
         writeTrigger(root, next, lock, config);
         lastState = stateKey;
@@ -118,15 +130,15 @@ export async function watchCommand(opts) {
   });
 }
 
-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];
+function pickNextAgent(root, lock, config) {
+  return resolveNextAgent(root, config, lock).next;
+}
 
-  const lastIndex = agentIds.indexOf(lastAgent);
-  return agentIds[(lastIndex + 1) % agentIds.length];
+function isValidClaimer(root, lock, config) {
+  if (!lock.holder || lock.holder === 'human') return true;
+  if (!config.agents?.[lock.holder]) return false;
+  const expected = pickNextAgent(root, lock, config);
+  return lock.holder === expected;
 }
 
 function forceRelease(root, lock, staleAgent, config) {
@@ -192,6 +204,39 @@ function blockOnValidation(root, lock, config, validation) {
   }
 }
 
+function blockOnIllegalClaim(root, lock, config, expected) {
+  const lockPath = join(root, LOCK_FILE);
+  const newLock = {
+    holder: 'human',
+    last_released_by: lock.last_released_by,
+    turn_number: lock.turn_number,
+    claimed_at: new Date().toISOString()
+  };
+  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+
+  const statePath = join(root, 'state.json');
+  if (existsSync(statePath)) {
+    try {
+      const current = JSON.parse(readFileSync(statePath, 'utf8'));
+      const nextState = {
+        ...current,
+        blocked: true,
+        blocked_on: `illegal-claim: expected ${expected}, got ${lock.holder}`
+      };
+      writeFileSync(statePath, JSON.stringify(nextState, null, 2) + '\n');
+    } catch {}
+  }
+
+  const logFile = config.log || 'log.md';
+  const logPath = join(root, logFile);
+  if (existsSync(logPath)) {
+    appendFileSync(
+      logPath,
+      `\n---\n\n### [system] (Watch Guard) | Turn ${lock.turn_number}\n\n**Status:** Illegal out-of-turn lock claim detected.\n\n**Action:** Lock assigned to human for intervention.\n\n**Details:** expected \`${expected}\`, got \`${lock.holder}\`.\n\n`
+    );
+  }
+}
+
 function log(type, msg) {
   const time = new Date().toLocaleTimeString();
   const tags = {

package/src/lib/generate-vscode.js

@@ -142,12 +142,13 @@ Create or update these files when your role requires it.
 
 The AgentXchain system coordinates turns. When prompted, do this:
 
-1. **CLAIM**: Write \`lock.json\` with \`holder="${agentId}"\` and \`claimed_at\` = current time. Re-read to confirm.
+1. **CLAIM**: Run \`agentxchain claim --agent ${agentId}\`. If blocked, stop.
 2. **READ**: ${readInstructions}
 3. **THINK**: What did the previous agent do? What is most important for YOUR role? What is one risk?
 4. **WORK**: ${writeInstructions}${verifyInstructions}
-5. **RELEASE**: Write \`lock.json\`: \`holder=null\`, \`last_released_by="${agentId}"\`, \`turn_number\` = previous + 1, \`claimed_at=null\`.
+5. **RELEASE**: Run \`agentxchain release --agent ${agentId}\`.
    This MUST be the last thing you write.
+6. **STOP**: End your turn. The referee will wake the next agent.
 
 ---
 
@@ -231,12 +232,29 @@ if [ -z "$HOLDER" ] || [ "$HOLDER" = "null" ]; then
   fi
 
   NEXT=$(node -e "
-    const cfg = JSON.parse(require('fs').readFileSync('agentxchain.json','utf8'));
-    const ids = Object.keys(cfg.agents);
-    const last = process.argv[1] || '';
+    const fs = require('fs');
+    const cfg = JSON.parse(fs.readFileSync('agentxchain.json','utf8'));
+    const ids = Object.keys(cfg.agents || {});
+    const lock = JSON.parse(fs.readFileSync('lock.json','utf8'));
+    const talkFile = cfg.talk_file || 'TALK.md';
+    let fromTalk = '';
+    try {
+      const talk = fs.readFileSync(talkFile, 'utf8').split(/\\r?\\n/);
+      for (let i = talk.length - 1; i >= 0; i -= 1) {
+        const m = talk[i].trim().match(/^(?:-|\\*)?\\s*\\**next\\s*owner\\**\\s*:\\s*(.+)$/i);
+        if (!m) continue;
+        let candidate = String(m[1] || '').replace(/[\\*_]/g, '').replace(/\\(.*?\\)/g, '').trim().split(/[\\s,]+/)[0].toLowerCase();
+        if (ids.includes(candidate)) { fromTalk = candidate; break; }
+      }
+    } catch {}
+    if (fromTalk) {
+      process.stdout.write(fromTalk);
+      process.exit(0);
+    }
+    const last = lock.last_released_by || '';
     const idx = ids.indexOf(last);
-    const next = ids[(idx + 1) % ids.length];
-    process.stdout.write(next);
+    const next = idx >= 0 ? ids[(idx + 1) % ids.length] : ids[0];
+    process.stdout.write(next || '');
   " -- "$LAST" 2>/dev/null)
 
   if [ -z "$NEXT" ]; then

package/src/lib/next-owner.js

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export function resolveNextAgent(root, config, lock = {}) {
+  const agents = Object.keys(config.agents || {});
+  if (agents.length === 0) return { next: null, source: 'none', raw: null };
+
+  const talkFile = config.talk_file || 'TALK.md';
+  const talkPath = join(root, talkFile);
+  const fromTalk = parseNextOwnerFromTalk(talkPath, agents);
+  if (fromTalk) {
+    return { next: fromTalk, source: 'talk', raw: fromTalk };
+  }
+
+  const last = lock.last_released_by;
+  if (last && agents.includes(last)) {
+    const idx = agents.indexOf(last);
+    return { next: agents[(idx + 1) % agents.length], source: 'fallback-cyclic', raw: null };
+  }
+
+  return { next: agents[0], source: 'fallback-first', raw: null };
+}
+
+function parseNextOwnerFromTalk(talkPath, validAgentIds) {
+  if (!existsSync(talkPath)) return null;
+
+  let text = '';
+  try {
+    text = readFileSync(talkPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  if (!text.trim()) return null;
+
+  const lines = text.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    const match = line.match(/^(?:-|\*)?\s*\**next\s*owner\**\s*:\s*(.+)$/i);
+    if (!match) continue;
+
+    const candidate = normalizeAgentId(match[1]);
+    if (candidate && validAgentIds.includes(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function normalizeAgentId(raw) {
+  if (!raw) return null;
+  let value = String(raw).trim();
+  value = value.replace(/[`*_]/g, '').trim();
+  value = value.replace(/\(.*?\)/g, '').trim();
+  value = value.split(/[,\s]+/)[0];
+  value = value.toLowerCase();
+  return /^[a-z0-9_-]+$/.test(value) ? value : null;
+}
+

package/src/lib/seed-prompt-polling.js

@@ -9,12 +9,6 @@ export function generatePollingPrompt(agentId, agentDef, config, projectRoot = '
 
   const agentIds = Object.keys(config.agents);
   const myIndex = agentIds.indexOf(agentId);
-  const prevAgent = myIndex === 0 ? null : agentIds[myIndex - 1];
-  const isFirstAgent = myIndex === 0;
-
-  const turnCondition = isFirstAgent
-    ? `It is YOUR turn when lock.json shows holder=null AND (last_released_by is null, "human", "system", OR the LAST agent in the rotation: "${agentIds[agentIds.length - 1]}")`
-    : `It is YOUR turn when lock.json shows holder=null AND last_released_by="${prevAgent}"`;
 
   const readSection = useSplit
     ? `READ THESE FILES:
@@ -37,6 +31,7 @@ c. Append ONE line to "${historyFile}":
    {"turn": N, "agent": "${agentId}", "summary": "what you did", "files_changed": [...], "verify_result": "pass|fail|skipped", "timestamp": "ISO8601"}
 d. Append ONE handoff entry to "${talkFile}" with:
    Turn, Status, Decision, Action, Risks/Questions, Next owner.
+   IMPORTANT: "Next owner" must be a valid agent id from [${agentIds.join(', ')}].
 e. Update state.json if phase or blocked status changed.`
     : `WRITE (in this order):
 a. Do your actual work: write code, create files, run commands, make decisions.
@@ -49,6 +44,7 @@ b. Append ONE message to ${logFile}:
    **Next:** What the next agent should focus on.
 c. Append ONE handoff entry to "${talkFile}" with:
    Turn, Status, Decision, Action, Risks/Questions, Next owner.
+   IMPORTANT: "Next owner" must be a valid agent id from [${agentIds.join(', ')}].
 d. Update state.json if phase or blocked status changed.`;
 
   const verifySection = verifyCmd
@@ -101,13 +97,13 @@ GET SHIT DONE FRAMEWORK (mandatory):
 
 ---
 
-TEAM ROTATION: ${agentIds.join(' → ')} → (repeat)
+TEAM IDS: ${agentIds.join(', ')}
 YOUR POSITION: ${agentId} (index ${myIndex} of ${agentIds.length})
-${turnCondition}
+Turn assignment is handoff-driven: previous owner writes "Next owner" in TALK.md.
 
 ---
 
-YOUR LOOP (run forever, never exit, never say "I'm done"):
+TURN MODE (single turn only, referee wakes you again later):
 
 0. CHECK WORKING DIRECTORY:
    - Run: pwd
@@ -115,20 +111,16 @@ YOUR LOOP (run forever, never exit, never say "I'm done"):
    - Never run broad searches outside this project root.
 
 1. READ lock.json.
+   Also read .agentxchain-trigger.json when present.
 
 2. CHECK — is it my turn?
-   - If holder is NOT null → someone else is working. Run the shell command: sleep 60
-     Then go back to step 1.
-   - If holder IS null → check last_released_by:
-     ${isFirstAgent
-       ? `- If last_released_by is null, "human", starts with "system", or "${agentIds[agentIds.length - 1]}" → IT IS YOUR TURN. Go to step 3.`
-       : `- If last_released_by is "${prevAgent}" → IT IS YOUR TURN. Go to step 3.`}
-     - Otherwise → it is another agent's turn. Run the shell command: sleep 60
-       Then go back to step 1.
+   - It is your turn when lock holder is null AND trigger.agent is "${agentId}".
+   - If trigger file is missing, you may still attempt claim; claim guardrails enforce expected next owner.
+   - If NOT your turn: STOP. Do not claim lock and do not write files.
 
 3. CLAIM the lock:
-   Write lock.json: {"holder":"${agentId}","last_released_by":<keep previous>,"turn_number":<keep previous>,"claimed_at":"<current ISO timestamp>"}
-   Then RE-READ lock.json immediately. If holder is not "${agentId}", someone else won. Go to step 1.
+   Run: agentxchain claim --agent ${agentId}
+   If claim is blocked, STOP.
 
 4. DO YOUR WORK:
    ${readSection}
@@ -142,20 +134,16 @@ YOUR LOOP (run forever, never exit, never say "I'm done"):
    If validation fails, fix docs/artifacts first. Do NOT release.
 
 5. RELEASE the lock:
-   Write lock.json: {"holder":null,"last_released_by":"${agentId}","turn_number":<previous + 1>,"claimed_at":null}
+   Run: agentxchain release --agent ${agentId}
    THIS MUST BE THE LAST FILE YOU WRITE.
 
-6. Run the shell command: sleep 60
-   Then go back to step 1.
-
 ---
 
 CRITICAL RULES:
-- ACTUALLY RUN "sleep 60" in the terminal between checks. Do NOT skip this. Do NOT just say "waiting."
 - Never write files or code without holding the lock. Reading is always allowed.
 - One git commit per turn: "Turn N - ${agentId} - description"
 - Max ${maxClaims} consecutive turns. If you have held the lock ${maxClaims} times in a row, do a short turn and release.
 - ALWAYS release the lock. A stuck lock blocks the entire team.
 - ALWAYS find at least one problem, risk, or question about the previous work. Blind agreement is forbidden.
-- NEVER exit or stop. After releasing, always sleep and poll again. You are a persistent agent.`;
+- This session is SINGLE-TURN. After release, STOP and wait for the referee to wake you again.`;
 }