agentxchain 2.155.21 → 2.155.23

package/README.md

@@ -205,6 +205,7 @@ Partial coordinator artifacts are first-class here too: `audit` and `report` kee
 | `multi init\|status\|step\|resume\|approve-gate\|resync` | Run the multi-repo coordinator lifecycle, including blocked-state recovery via `multi resume` |
 | `intake record\|triage\|approve\|plan\|start\|scan\|resolve` | Continuous-delivery intake: turn delivery signals into governed work items |
 | `intake handoff` | Bridge a planned intake intent to a coordinator workstream for multi-repo execution |
+| `watch --event-file\|--event-dir\|--results\|--result` | Normalize external events into governed intake, poll event-file directories, and inspect durable watch result records |
 | `schedule list\|run-due\|daemon\|status` | Run repo-local lights-out scheduling: inspect schedules, execute due runs, poll in a local daemon loop, continue explicitly unblocked schedule-owned runs, or check daemon heartbeat |
 | `plugin install\|list\|remove` | Install, inspect, or remove governed hook plugins under `.agentxchain/plugins/` |
 | `plugin list-available` | List bundled built-in plugins installable by short name |

package/bin/agentxchain.js

@@ -248,8 +248,16 @@ generateCmd
 
 program
   .command('watch')
-  .description('Watch lock.json and coordinate agent turns (the referee)')
+  .description('Watch lock.json, or ingest an external event into governed intake')
   .option('--daemon', 'Run in background mode')
+  .option('--event-file <path>', 'Normalize one external event JSON file into governed intake')
+  .option('--event-dir <path>', 'Poll a directory for external event JSON files')
+  .option('--poll-seconds <seconds>', 'With --event-dir, polling interval in seconds', '5')
+  .option('--dry-run', 'With --event-file, print the normalized intake payload without writing')
+  .option('--results', 'List all watch result records')
+  .option('--result <id>', 'Show a single watch result by ID or filename')
+  .option('--limit <n>', 'With --results, limit the number of results shown')
+  .option('-j, --json', 'Output JSON')
   .action(watchCommand);
 
 program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.155.21",
+  "version": "2.155.23",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/scripts/release-bump.sh

@@ -79,6 +79,7 @@ ALLOWED_RELEASE_PATHS=(
   ".agentxchain-conformance/capabilities.json"
   "website-v2/docs/protocol-implementor-guide.mdx"
   ".planning/LAUNCH_EVIDENCE_REPORT.md"
+  ".planning/HN_LAUNCH_SURFACE_ALIGNMENT_SPEC.md"
   ".planning/SHOW_HN_DRAFT.md"
   ".planning/MARKETING/TWITTER_THREAD.md"
   ".planning/MARKETING/LINKEDIN_POST.md"
@@ -88,6 +89,7 @@ ALLOWED_RELEASE_PATHS=(
   "website-v2/docs/getting-started.mdx"
   "website-v2/docs/quickstart.mdx"
   "website-v2/docs/five-minute-tutorial.mdx"
+  "cli/test/hn-launch-surface-content.test.js"
   "cli/homebrew/agentxchain.rb"
   "cli/homebrew/README.md"
 )

package/src/commands/watch.js

@@ -1,19 +1,42 @@
-import { readFileSync, writeFileSync, existsSync, appendFileSync, unlinkSync } from 'fs';
-import { join, dirname } from 'path';
+import { readFileSync, writeFileSync, existsSync, appendFileSync, unlinkSync, mkdirSync, readdirSync, renameSync, statSync } from 'fs';
+import { join, dirname, basename, resolve } 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 { recordEvent, triageIntent, approveIntent, planIntent, startIntent } from '../lib/intake.js';
+import { normalizeWatchEvent, resolveWatchRoute, writeWatchResult } from '../lib/watch-events.js';
 import { safeWriteJson } from '../lib/safe-write.js';
 import { notifyHuman as sendNotification } from '../lib/notify.js';
 import { validateProject } from '../lib/validation.js';
 import { resolveNextAgent, resolveExpectedClaimer } from '../lib/next-owner.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 const PID_FILE = '.agentxchain-watch.pid';
 
 export async function watchCommand(opts) {
+  if (opts.results || opts.result) {
+    listOrShowWatchResults(opts);
+    return;
+  }
+
+  if (opts.eventFile) {
+    await ingestWatchEvent(opts);
+    return;
+  }
+
+  if (opts.daemon && opts.eventDir && process.env.AGENTXCHAIN_WATCH_DAEMON !== '1') {
+    startWatchDaemon(opts);
+    return;
+  }
+
+  if (opts.eventDir) {
+    await watchEventDirectory(opts);
+    return;
+  }
+
   if (opts.daemon && process.env.AGENTXCHAIN_WATCH_DAEMON !== '1') {
-    startWatchDaemon();
+    startWatchDaemon(opts);
     return;
   }
 
@@ -153,6 +176,481 @@ export async function watchCommand(opts) {
   process.on('SIGTERM', cleanup);
 }
 
+async function watchEventDirectory(opts) {
+  const root = requireIntakeWorkspaceOrExit(opts);
+  const eventDir = resolve(process.cwd(), opts.eventDir);
+  const pollMs = parsePollMs(opts.pollSeconds);
+  mkdirSync(eventDir, { recursive: true });
+  writePidFile(root);
+
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Watch Event Directory'));
+  console.log(chalk.dim(`  Event dir: ${eventDir}`));
+  console.log(chalk.dim(`  Poll:      ${pollMs}ms`));
+  console.log(chalk.dim('  Processed files move to processed/; failed files move to failed/.'));
+  console.log('');
+
+  let processing = false;
+  const tick = async () => {
+    if (processing) return;
+    processing = true;
+    try {
+      const results = await processPendingEventFiles(root, eventDir);
+      for (const result of results) {
+        if (result.ok) {
+          log('claimed', `Processed event file ${basename(result.source)} -> ${basename(result.destination)}`);
+        } else {
+          log('warn', `Failed event file ${basename(result.source)} -> ${basename(result.destination)}: ${result.error}`);
+        }
+      }
+    } catch (err) {
+      log('error', err.message);
+    } finally {
+      processing = false;
+    }
+  };
+
+  await tick();
+  const timer = setInterval(tick, pollMs);
+
+  const cleanup = () => {
+    clearInterval(timer);
+    removePidFile(root);
+    console.log('');
+    log('stop', 'Watch event directory stopped.');
+    process.exit(0);
+  };
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+}
+
+async function processPendingEventFiles(root, eventDir) {
+  const entries = readdirSync(eventDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => entry.name)
+    .sort();
+
+  const results = [];
+  for (const name of entries) {
+    const source = join(eventDir, name);
+    if (!existsSync(source)) continue;
+
+    const childResult = await runWatchEventFile(root, source);
+    const destinationDir = join(eventDir, childResult.status === 0 ? 'processed' : 'failed');
+    const destination = moveEventFile(source, destinationDir);
+    results.push({
+      ok: childResult.status === 0,
+      source,
+      destination,
+      error: childResult.status === 0 ? null : summarizeChildFailure(childResult),
+    });
+  }
+  return results;
+}
+
+const DEFAULT_CHILD_TIMEOUT_MS = 30_000;
+
+function runWatchEventFile(root, eventFile, timeoutMs = DEFAULT_CHILD_TIMEOUT_MS) {
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  const cliBin = join(currentDir, '../../bin/agentxchain.js');
+  return new Promise((resolvePromise) => {
+    const child = spawn(process.execPath, [cliBin, 'watch', '--event-file', eventFile, '--json'], {
+      cwd: root,
+      env: { ...process.env, NO_COLOR: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (status, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolvePromise({ status: status ?? 1, signal, stdout, stderr });
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      try { child.kill('SIGTERM'); } catch {}
+      stderr += `\nchild process timed out after ${timeoutMs}ms`;
+      finish(1, 'SIGTERM');
+    }, timeoutMs);
+    child.stdout.on('data', (data) => { stdout += data.toString(); });
+    child.stderr.on('data', (data) => { stderr += data.toString(); });
+    child.on('close', (status, signal) => finish(status, signal));
+    child.on('error', (err) => {
+      stderr += err.message;
+      finish(1, null);
+    });
+  });
+}
+
+function moveEventFile(source, destinationDir) {
+  mkdirSync(destinationDir, { recursive: true });
+  const parsed = basename(source);
+  let destination = join(destinationDir, parsed);
+  if (existsSync(destination)) {
+    const suffix = `${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
+    destination = join(destinationDir, `${parsed}.${suffix}`);
+  }
+  renameSync(source, destination);
+  return destination;
+}
+
+function summarizeChildFailure(result) {
+  try {
+    const parsed = JSON.parse(result.stdout);
+    if (parsed?.error) return parsed.error;
+  } catch {}
+  return result.stderr.trim() || result.stdout.trim() || `watch --event-file exited with status ${result.status}`;
+}
+
+function parsePollMs(value) {
+  const seconds = Number(value);
+  if (!Number.isFinite(seconds) || seconds <= 0) return 5000;
+  return Math.max(100, Math.round(seconds * 1000));
+}
+
+async function ingestWatchEvent(opts) {
+  if (opts.daemon) {
+    const message = '--daemon cannot be combined with --event-file';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    } else {
+      console.log(chalk.red(`  ${message}`));
+    }
+    process.exit(1);
+  }
+
+  const root = requireIntakeWorkspaceOrExit(opts);
+  let raw;
+  let parsed;
+  try {
+    raw = readFileSync(opts.eventFile, 'utf8');
+  } catch (err) {
+    const message = `failed to read event file: ${err.message}`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    } else {
+      console.log(chalk.red(`  ${message}`));
+    }
+    process.exit(1);
+  }
+
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const message = `event file is not valid JSON: ${err.message}`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    } else {
+      console.log(chalk.red(`  ${message}`));
+    }
+    process.exit(1);
+  }
+
+  let payload;
+  try {
+    payload = normalizeWatchEvent(parsed);
+  } catch (err) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: err.message }, null, 2));
+    } else {
+      console.log(chalk.red(`  ${err.message}`));
+    }
+    process.exit(1);
+  }
+
+  if (opts.dryRun) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, dry_run: true, payload }, null, 2));
+    } else {
+      console.log('');
+      console.log(chalk.green('  Watch event normalized (dry run)'));
+      console.log(JSON.stringify(payload, null, 2));
+      console.log('');
+    }
+    process.exit(0);
+  }
+
+  const result = recordEvent(root, payload);
+  if (!result.ok) {
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(chalk.red(`  ${result.error}`));
+    }
+    process.exit(result.exitCode);
+  }
+
+  // Route-based auto-triage and auto-approve
+  let routed = null;
+  if (!result.deduplicated && result.intent) {
+    let routes;
+    try {
+      const rawConfig = JSON.parse(readFileSync(join(root, 'agentxchain.json'), 'utf8'));
+      routes = rawConfig?.watch?.routes;
+    } catch {
+      // non-fatal — no routes if config is unreadable
+    }
+    const resolved = resolveWatchRoute(payload, routes);
+    if (resolved) {
+      const triageFields = {
+        ...resolved.triage,
+      };
+      if (resolved.preferred_role) {
+        triageFields.preferred_role = resolved.preferred_role;
+      }
+      const triageResult = triageIntent(root, result.intent.intent_id, triageFields);
+      if (triageResult.ok) {
+        result.intent = triageResult.intent;
+        routed = { triaged: true, approved: false, preferred_role: resolved.preferred_role };
+        if (resolved.auto_approve) {
+          const approveResult = approveIntent(root, result.intent.intent_id, {
+            approver: 'watch_route',
+            reason: `auto-approved by watch route matching ${payload.category}`,
+          });
+          if (approveResult.ok) {
+            result.intent = approveResult.intent;
+            routed.approved = true;
+
+            // Auto-start: plan + start the governed run
+            if (resolved.auto_start) {
+              const planResult = planIntent(root, result.intent.intent_id, {
+                force: resolved.overwrite_planning_artifacts === true,
+              });
+              if (planResult.ok) {
+                result.intent = planResult.intent;
+                routed.planned = true;
+
+                const startResult = startIntent(root, result.intent.intent_id, {});
+                if (startResult.ok) {
+                  result.intent = startResult.intent;
+                  routed.started = true;
+                  routed.run_id = startResult.run_id || null;
+                  routed.role = startResult.role || null;
+                } else {
+                  routed.started = false;
+                  routed.auto_start_error = startResult.error;
+                }
+              } else {
+                routed.planned = false;
+                routed.started = false;
+                routed.auto_start_error = planResult.error;
+              }
+            }
+          }
+        } else if (resolved.auto_start) {
+          // auto_start without auto_approve — skip silently
+          routed.auto_start_skipped = 'requires auto_approve';
+        }
+      }
+    }
+  }
+
+  if (routed) {
+    result.routed = routed;
+  }
+
+  // Write durable watch result file
+  const watchResult = writeWatchResult(root, result, payload);
+  result.watch_result_id = watchResult.result_id;
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log('');
+    if (result.deduplicated) {
+      console.log(chalk.yellow(`  Watch event already recorded: ${result.event.event_id} (deduplicated)`));
+      if (result.intent) {
+        console.log(chalk.dim(`  Linked intent: ${result.intent.intent_id} (${result.intent.status})`));
+      }
+    } else {
+      console.log(chalk.green(`  Recorded watch event ${result.event.event_id}`));
+      console.log(chalk.green(`  Created intent ${result.intent.intent_id} (${result.intent.status})`));
+      if (routed) {
+        const parts = [`triaged=${routed.triaged}`, `approved=${routed.approved}`];
+        if (routed.preferred_role) parts.push(`role=${routed.preferred_role}`);
+        if (routed.planned) parts.push('planned=true');
+        if (routed.started) parts.push(`started=true`);
+        if (routed.auto_start_error) parts.push(`start_error="${routed.auto_start_error}"`);
+        if (routed.auto_start_skipped) parts.push(`auto_start_skipped`);
+        console.log(chalk.cyan(`  Route matched: ${parts.join(', ')}`));
+      }
+    }
+    console.log('');
+  }
+  process.exit(result.exitCode);
+}
+
+// ---------------------------------------------------------------------------
+// Watch results inspection
+// ---------------------------------------------------------------------------
+
+function listOrShowWatchResults(opts) {
+  const root = requireIntakeWorkspaceOrExit(opts);
+  const resultsDir = join(root, '.agentxchain', 'watch-results');
+
+  if (!existsSync(resultsDir)) {
+    if (opts.json) {
+      console.log(JSON.stringify(opts.result ? { ok: false, error: 'no watch results found' } : { ok: true, results: [] }, null, 2));
+    } else {
+      console.log(chalk.dim('  No watch results yet.'));
+    }
+    process.exit(opts.result ? 1 : 0);
+  }
+
+  // Show a single result by ID or filename
+  if (opts.result) {
+    const record = loadWatchResult(resultsDir, opts.result);
+    if (!record) {
+      if (opts.json) {
+        console.log(JSON.stringify({ ok: false, error: `watch result not found: ${opts.result}` }, null, 2));
+      } else {
+        console.log(chalk.red(`  Watch result not found: ${opts.result}`));
+      }
+      process.exit(1);
+    }
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, ...record }, null, 2));
+    } else {
+      printWatchResult(record);
+    }
+    process.exit(0);
+  }
+
+  // List all results
+  const entries = readdirSync(resultsDir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith('.json'))
+    .map((e) => e.name)
+    .sort();
+
+  const records = [];
+  for (const name of entries) {
+    try {
+      const content = JSON.parse(readFileSync(join(resultsDir, name), 'utf8'));
+      records.push(content);
+    } catch {
+      // skip corrupt files
+    }
+  }
+
+  // Sort by timestamp descending (most recent first)
+  records.sort((a, b) => (b.timestamp || '').localeCompare(a.timestamp || ''));
+
+  // Apply --limit if provided
+  const limit = opts.limit ? parseInt(opts.limit, 10) : 0;
+  const display = limit > 0 ? records.slice(0, limit) : records;
+
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: true, total: records.length, results: display }, null, 2));
+    process.exit(0);
+  }
+
+  console.log('');
+  console.log(chalk.bold(`  Watch Results (${records.length} total)`));
+  console.log('');
+
+  if (display.length === 0) {
+    console.log(chalk.dim('  No watch results yet.'));
+    console.log('');
+    process.exit(0);
+  }
+
+  for (const r of display) {
+    const status = formatResultStatus(r);
+    const category = r.payload?.category || 'unknown';
+    const repo = r.payload?.repo || '';
+    const ts = r.timestamp ? new Date(r.timestamp).toLocaleString() : 'unknown';
+    const dedup = r.deduplicated ? chalk.yellow(' [dedup]') : '';
+    const errors = r.errors?.length > 0 ? chalk.red(` (${r.errors.length} error${r.errors.length > 1 ? 's' : ''})`) : '';
+
+    console.log(`  ${chalk.dim(r.result_id)}  ${status}${dedup}${errors}`);
+    console.log(`    ${chalk.cyan(category)} ${repo ? chalk.dim(repo) : ''} ${chalk.dim(ts)}`);
+    if (r.route?.run_id) {
+      console.log(`    ${chalk.dim('run:')} ${r.route.run_id} ${chalk.dim('role:')} ${r.route.role || '?'}`);
+    }
+  }
+
+  if (limit > 0 && records.length > limit) {
+    console.log(chalk.dim(`\n  ... and ${records.length - limit} more. Use --limit 0 to show all.`));
+  }
+
+  console.log('');
+  process.exit(0);
+}
+
+function loadWatchResult(resultsDir, idOrFile) {
+  // Try exact filename first
+  const directPath = join(resultsDir, idOrFile.endsWith('.json') ? idOrFile : `${idOrFile}.json`);
+  if (existsSync(directPath)) {
+    try { return JSON.parse(readFileSync(directPath, 'utf8')); } catch { return null; }
+  }
+
+  // Search by result_id prefix
+  const entries = readdirSync(resultsDir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith('.json'));
+  for (const entry of entries) {
+    try {
+      const content = JSON.parse(readFileSync(join(resultsDir, entry.name), 'utf8'));
+      if (content.result_id === idOrFile || content.result_id?.startsWith(idOrFile)) {
+        return content;
+      }
+    } catch {
+      // skip corrupt
+    }
+  }
+  return null;
+}
+
+function formatResultStatus(r) {
+  if (r.deduplicated) return chalk.yellow('deduplicated');
+  if (!r.route?.matched) return chalk.dim('unrouted');
+  if (r.route.started) return chalk.green('started');
+  if (r.route.planned) return chalk.blue('planned');
+  if (r.route.approved) return chalk.cyan('approved');
+  if (r.route.triaged) return chalk.white('triaged');
+  return chalk.dim('detected');
+}
+
+function printWatchResult(r) {
+  console.log('');
+  console.log(chalk.bold('  Watch Result'));
+  console.log(`  ${chalk.dim('ID:')}        ${r.result_id}`);
+  console.log(`  ${chalk.dim('Time:')}      ${r.timestamp ? new Date(r.timestamp).toLocaleString() : 'unknown'}`);
+  console.log(`  ${chalk.dim('Event:')}     ${r.event_id || 'none'}`);
+  console.log(`  ${chalk.dim('Intent:')}    ${r.intent_id || 'none'} (${r.intent_status || '?'})`);
+  console.log(`  ${chalk.dim('Dedup:')}     ${r.deduplicated ? 'yes' : 'no'}`);
+  console.log('');
+  console.log(chalk.bold('  Payload'));
+  console.log(`  ${chalk.dim('Source:')}    ${r.payload?.source || '?'}`);
+  console.log(`  ${chalk.dim('Category:')} ${r.payload?.category || '?'}`);
+  console.log(`  ${chalk.dim('Repo:')}      ${r.payload?.repo || 'none'}`);
+  console.log(`  ${chalk.dim('Ref:')}       ${r.payload?.ref || 'none'}`);
+  console.log('');
+  console.log(chalk.bold('  Route'));
+  if (!r.route?.matched) {
+    console.log(chalk.dim('  No matching route.'));
+  } else {
+    console.log(`  ${chalk.dim('Triaged:')}   ${r.route.triaged ? 'yes' : 'no'}`);
+    console.log(`  ${chalk.dim('Approved:')}  ${r.route.approved ? 'yes' : 'no'}`);
+    console.log(`  ${chalk.dim('Planned:')}   ${r.route.planned ? 'yes' : 'no'}`);
+    console.log(`  ${chalk.dim('Started:')}   ${r.route.started ? 'yes' : 'no'}`);
+    console.log(`  ${chalk.dim('Auto-start:')} ${r.route.auto_start ? 'yes' : 'no'}`);
+    if (r.route.preferred_role) console.log(`  ${chalk.dim('Role hint:')} ${r.route.preferred_role}`);
+    if (r.route.run_id) console.log(`  ${chalk.dim('Run ID:')}    ${r.route.run_id}`);
+    if (r.route.role) console.log(`  ${chalk.dim('Role:')}      ${r.route.role}`);
+  }
+  if (r.errors?.length > 0) {
+    console.log('');
+    console.log(chalk.bold('  Errors'));
+    for (const err of r.errors) {
+      console.log(`  ${chalk.red('•')} ${err}`);
+    }
+  }
+  console.log('');
+}
+
 function pickNextAgent(root, lock, config) {
   return resolveNextAgent(root, config, lock).next;
 }
@@ -307,10 +805,15 @@ function log(type, msg) {
   console.log(`  ${chalk.dim(time)} ${tags[type] || chalk.dim(type)}  ${msg}`);
 }
 
-function startWatchDaemon() {
+function startWatchDaemon(opts = {}) {
   const currentDir = dirname(fileURLToPath(import.meta.url));
   const cliBin = join(currentDir, '../../bin/agentxchain.js');
-  const child = spawn(process.execPath, [cliBin, 'watch'], {
+  const args = [cliBin, 'watch'];
+  if (opts.eventDir) {
+    args.push('--event-dir', opts.eventDir);
+    if (opts.pollSeconds) args.push('--poll-seconds', String(opts.pollSeconds));
+  }
+  const child = spawn(process.execPath, args, {
     cwd: process.cwd(),
     detached: true,
     stdio: 'ignore',
@@ -319,8 +822,12 @@ function startWatchDaemon() {
   child.unref();
 
   const result = loadConfig();
-  if (result) {
-    writeFileSync(join(result.root, PID_FILE), String(child.pid));
+  let pidRoot = result?.root || null;
+  if (!pidRoot && opts.eventDir && existsSync(join(process.cwd(), 'agentxchain.json'))) {
+    pidRoot = process.cwd();
+  }
+  if (pidRoot) {
+    writeFileSync(join(pidRoot, PID_FILE), String(child.pid));
   }
 
   console.log('');

package/src/lib/config.js

@@ -9,6 +9,7 @@ import {
   reconcileApprovalPausesWithConfig,
   reconcileBudgetStatusWithConfig,
   reconcileRecoveryActionsWithConfig,
+  recoverStaleIdleExpansionRun,
 } from './governed-state.js';
 
 function attachLegacyCurrentTurnAlias(state) {
@@ -160,7 +161,10 @@ export function loadProjectState(root, config) {
     stateData = reconciledBudget.state;
     const reconciledRecovery = reconcileRecoveryActionsWithConfig(stateData, config);
     stateData = reconciledRecovery.state;
-    if (normalized.changed || reconciledApprovals.changed || reconciledBudget.changed || reconciledRecovery.changed) {
+    // BUG-75: recover stale idle-expansion runs missing charter_materialization_pending
+    const staleRecovery = recoverStaleIdleExpansionRun(root, stateData);
+    stateData = staleRecovery.state;
+    if (normalized.changed || reconciledApprovals.changed || reconciledBudget.changed || reconciledRecovery.changed || staleRecovery.changed) {
       safeWriteJson(filePath, stateData);
     }
   }

package/src/lib/governed-state.js

@@ -2500,6 +2500,99 @@ export function normalizeGovernedStateShape(state) {
   return { state: stripLegacyCurrentTurn(nextState), changed };
 }
 
+// BUG-75: Recover stale idle-expansion runs created before BUG-74 that lack
+// charter_materialization_pending. These runs loop on gate_semantic_coverage
+// because the PM prompt never receives the materialization directive.
+const INTAKE_EVENTS_DIR = '.agentxchain/intake/events';
+
+export function recoverStaleIdleExpansionRun(root, state) {
+  if (!state || typeof state !== 'object') {
+    return { state, changed: false };
+  }
+
+  // Only recover active planning runs missing the materialization flag
+  if (
+    state.status !== 'active'
+    || state.phase !== 'planning'
+    || state.charter_materialization_pending
+  ) {
+    return { state, changed: false };
+  }
+
+  // Trace the run back to its intake intent via provenance
+  const intentId = state.provenance?.intake_intent_id;
+  if (!intentId) {
+    return { state, changed: false };
+  }
+
+  // Read the intent file
+  const intentPath = join(root, INTAKE_INTENTS_DIR, `${intentId}.json`);
+  if (!existsSync(intentPath)) {
+    return { state, changed: false };
+  }
+
+  let intent;
+  try {
+    intent = JSON.parse(readFileSync(intentPath, 'utf8'));
+  } catch {
+    return { state, changed: false };
+  }
+
+  const eventId = intent.event_id;
+  if (!eventId) {
+    return { state, changed: false };
+  }
+
+  // Read the event file to check the category
+  const eventPath = join(root, INTAKE_EVENTS_DIR, `${eventId}.json`);
+  if (!existsSync(eventPath)) {
+    return { state, changed: false };
+  }
+
+  let event;
+  try {
+    event = JSON.parse(readFileSync(eventPath, 'utf8'));
+  } catch {
+    return { state, changed: false };
+  }
+
+  if (event.category !== 'pm_idle_expansion_derived') {
+    return { state, changed: false };
+  }
+
+  // Reconstruct charter_materialization_pending from the intake context
+  const recoveredState = {
+    ...state,
+    charter_materialization_pending: {
+      charter: intent.charter || null,
+      acceptance_contract: Array.isArray(intent.acceptance_contract)
+        ? intent.acceptance_contract
+        : [],
+      suppressed_transition: 'implementation',
+      source_turn_id: null,
+      recorded_at: new Date().toISOString(),
+    },
+  };
+
+  // Emit recovery event
+  emitRunEvent(root, 'charter_materialization_required', {
+    run_id: state.run_id,
+    phase: state.phase,
+    status: state.status,
+    payload: {
+      suppressed_transition: 'implementation',
+      reason: 'Stale run from idle-expansion-derived intent recovered missing charter_materialization_pending flag.',
+      new_intake_charter: intent.charter || null,
+      source: 'stale_run_recovery',
+      recovered_missing_flag: true,
+      intent_id: intentId,
+      event_id: eventId,
+    },
+  });
+
+  return { state: recoveredState, changed: true };
+}
+
 export function markRunBlocked(root, details) {
   const state = readState(root);
   if (!state) {

package/src/lib/intake.js

@@ -537,6 +537,9 @@ export function triageIntent(root, intentId, fields) {
   intent.charter = normalizedFields.charter;
   intent.acceptance_contract = normalizedFields.acceptance_contract;
   intent.phase_scope = normalizedFields.phase_scope || null;
+  if (normalizedFields.preferred_role) {
+    intent.preferred_role = normalizedFields.preferred_role;
+  }
   intent.updated_at = now;
   intent.history.push({ from: 'detected', to: 'triaged', at: now, reason: 'triage completed' });
 
@@ -1148,7 +1151,7 @@ export function startIntent(root, intentId, options = {}) {
   }
 
   // Resolve role
-  const roleId = resolveIntakeRole(options.role, state, config);
+  const roleId = resolveIntakeRole(options.role, intent, state, config);
   if (!roleId.ok) {
     return { ok: false, error: roleId.error, exitCode: 1 };
   }
@@ -1220,7 +1223,7 @@ export function startIntent(root, intentId, options = {}) {
   };
 }
 
-function resolveIntakeRole(roleOverride, state, config) {
+function resolveIntakeRole(roleOverride, intent, state, config) {
   const phase = state.phase;
   const routing = config.routing?.[phase];
 
@@ -1232,6 +1235,17 @@ function resolveIntakeRole(roleOverride, state, config) {
     return { ok: true, role: roleOverride };
   }
 
+  const preferredRole = typeof intent?.preferred_role === 'string'
+    ? intent.preferred_role.trim()
+    : '';
+  if (preferredRole) {
+    if (!config.roles?.[preferredRole]) {
+      const available = Object.keys(config.roles || {}).join(', ');
+      return { ok: false, error: `unknown preferred_role on intent: "${preferredRole}". Available: ${available}` };
+    }
+    return { ok: true, role: preferredRole };
+  }
+
   if (routing?.entry_role) {
     return { ok: true, role: routing.entry_role };
   }

package/src/lib/watch-events.js

@@ -0,0 +1,311 @@
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+import { safeWriteJson } from './safe-write.js';
+
+export function normalizeWatchEvent(input) {
+  const event = unwrapEvent(input);
+
+  if (isPullRequestEvent(event)) {
+    return normalizePullRequestEvent(event);
+  }
+
+  if (isIssueLabeledEvent(event)) {
+    return normalizeIssueLabeledEvent(event);
+  }
+
+  if (isWorkflowFailureEvent(event)) {
+    return normalizeWorkflowFailureEvent(event);
+  }
+
+  if (isScheduleEvent(event)) {
+    return normalizeScheduleEvent(event);
+  }
+
+  throw new Error('unsupported watch event: supported events are GitHub pull_request, issues.labeled, failed workflow_run, and schedule');
+}
+
+function unwrapEvent(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('watch event must be a JSON object');
+  }
+
+  if (input.provider === 'github' && typeof input.event === 'string') {
+    return {
+      provider: 'github',
+      event: input.event,
+      ...(input.payload && typeof input.payload === 'object' && !Array.isArray(input.payload) ? input.payload : input),
+    };
+  }
+
+  return {
+    provider: input.provider || 'github',
+    event: inferGitHubEvent(input),
+    ...input,
+  };
+}
+
+function inferGitHubEvent(event) {
+  if (event.pull_request) return 'pull_request';
+  if (event.issue) return 'issues';
+  if (event.workflow_run) return 'workflow_run';
+  if (event.schedule || event.event === 'schedule') return 'schedule';
+  return event.event || 'unknown';
+}
+
+function isPullRequestEvent(event) {
+  return event.provider === 'github' && event.event === 'pull_request' && event.pull_request;
+}
+
+function isIssueLabeledEvent(event) {
+  return event.provider === 'github' && event.event === 'issues' && event.action === 'labeled' && event.issue;
+}
+
+function isWorkflowFailureEvent(event) {
+  if (event.provider !== 'github' || event.event !== 'workflow_run' || !event.workflow_run) return false;
+  const conclusion = event.workflow_run.conclusion;
+  return typeof conclusion === 'string' && !['success', 'skipped', 'cancelled'].includes(conclusion);
+}
+
+function isScheduleEvent(event) {
+  return event.provider === 'github' && event.event === 'schedule';
+}
+
+function normalizePullRequestEvent(event) {
+  const pr = event.pull_request;
+  const repo = repositoryName(event);
+  const action = normalizeToken(event.action || 'unknown');
+  const signal = removeNullish({
+    provider: 'github',
+    event: 'pull_request',
+    action,
+    repository: repo,
+    number: pr.number,
+    title: pr.title,
+    url: pr.html_url,
+    head_ref: pr.head?.ref,
+    head_sha: pr.head?.sha,
+    base_ref: pr.base?.ref,
+    draft: pr.draft,
+  });
+
+  return {
+    source: 'git_ref_change',
+    category: `github_pull_request_${action}`,
+    repo,
+    ref: pr.head?.ref || null,
+    signal,
+    evidence: evidenceFor(pr.html_url, pr.title || `Pull request ${pr.number || ''}`.trim()),
+  };
+}
+
+function normalizeIssueLabeledEvent(event) {
+  const issue = event.issue;
+  const repo = repositoryName(event);
+  const labelName = typeof event.label?.name === 'string' ? event.label.name : null;
+  const signal = removeNullish({
+    provider: 'github',
+    event: 'issues',
+    action: 'labeled',
+    repository: repo,
+    number: issue.number,
+    title: issue.title,
+    url: issue.html_url,
+    label: labelName,
+  });
+
+  return {
+    source: 'manual',
+    category: 'github_issue_labeled',
+    repo,
+    ref: null,
+    signal,
+    evidence: evidenceFor(issue.html_url, issue.title || `Issue ${issue.number || ''}`.trim()),
+  };
+}
+
+function normalizeWorkflowFailureEvent(event) {
+  const workflowRun = event.workflow_run;
+  const repo = repositoryName(event);
+  const signal = removeNullish({
+    provider: 'github',
+    event: 'workflow_run',
+    action: normalizeToken(event.action || 'completed'),
+    repository: repo,
+    workflow_name: workflowRun.name,
+    conclusion: workflowRun.conclusion,
+    status: workflowRun.status,
+    run_id: workflowRun.id,
+    run_number: workflowRun.run_number,
+    url: workflowRun.html_url,
+    head_branch: workflowRun.head_branch,
+    head_sha: workflowRun.head_sha,
+  });
+
+  return {
+    source: 'ci_failure',
+    category: 'github_workflow_run_failed',
+    repo,
+    ref: workflowRun.head_branch || null,
+    signal,
+    evidence: evidenceFor(workflowRun.html_url, `${workflowRun.name || 'GitHub workflow'} ${workflowRun.conclusion || 'failed'}`),
+  };
+}
+
+function normalizeScheduleEvent(event) {
+  const repo = repositoryName(event);
+  const signal = removeNullish({
+    provider: 'github',
+    event: 'schedule',
+    repository: repo,
+    schedule: event.schedule,
+    workflow: event.workflow,
+    ref: event.ref,
+    sha: event.sha,
+  });
+
+  return {
+    source: 'schedule',
+    category: 'github_schedule',
+    repo,
+    ref: event.ref || null,
+    signal,
+    evidence: [{ type: 'text', value: `GitHub schedule event${event.schedule ? `: ${event.schedule}` : ''}` }],
+  };
+}
+
+function repositoryName(event) {
+  if (typeof event.repository === 'string') return event.repository;
+  if (typeof event.repository?.full_name === 'string') return event.repository.full_name;
+  if (typeof event.repository?.name === 'string') return event.repository.name;
+  return null;
+}
+
+function evidenceFor(url, text) {
+  if (typeof url === 'string' && url.trim()) {
+    return [{ type: 'url', value: url }];
+  }
+  return [{ type: 'text', value: text || 'GitHub event' }];
+}
+
+function normalizeToken(value) {
+  return String(value || 'unknown').trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'unknown';
+}
+
+function removeNullish(input) {
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== null && value !== undefined && value !== ''));
+}
+
+// ---------------------------------------------------------------------------
+// Route resolution
+// ---------------------------------------------------------------------------
+
+export function resolveWatchRoute(payload, routes) {
+  if (!Array.isArray(routes) || routes.length === 0) return null;
+
+  for (const route of routes) {
+    if (!route.match || !route.triage) continue;
+
+    const match = route.match;
+    if (match.source && match.source !== payload.source) continue;
+    if (match.category) {
+      if (match.category.includes('*')) {
+        const escaped = match.category.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+        if (!new RegExp(`^${escaped}$`).test(payload.category)) continue;
+      } else if (match.category !== payload.category) {
+        continue;
+      }
+    }
+
+    const charter = interpolateCharter(route.triage.charter, payload.signal);
+
+    return {
+      triage: {
+        priority: route.triage.priority || 'p2',
+        template: route.triage.template || 'generic',
+        charter,
+        acceptance_contract: Array.isArray(route.triage.acceptance_contract) && route.triage.acceptance_contract.length > 0
+          ? route.triage.acceptance_contract
+          : ['Watch event processed under governance'],
+      },
+      auto_approve: route.auto_approve === true,
+      auto_start: route.auto_start === true,
+      overwrite_planning_artifacts: route.overwrite_planning_artifacts === true,
+      preferred_role: route.preferred_role || null,
+    };
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Watch result persistence
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a durable watch result file to `.agentxchain/watch-results/`.
+ *
+ * Every non-dry-run `watch --event-file` invocation writes exactly one result
+ * file containing the full pipeline trace: event, intent, route match,
+ * triage/approve/plan/start statuses, errors, and timestamps.
+ *
+ * @param {string} root - project root
+ * @param {object} pipelineResult - the result object from ingestWatchEvent
+ * @param {object} payload - the normalized watch event payload
+ * @returns {{ result_id: string, result_path: string }}
+ */
+export function writeWatchResult(root, pipelineResult, payload) {
+  const ts = Date.now();
+  const suffix = Math.random().toString(16).slice(2, 10);
+  const resultId = `wr_${ts}_${suffix}`;
+
+  const routed = pipelineResult.routed || null;
+  const errors = [];
+
+  if (routed?.auto_start_error) errors.push(routed.auto_start_error);
+  if (routed?.auto_start_skipped) errors.push(`auto_start_skipped: ${routed.auto_start_skipped}`);
+
+  const record = {
+    result_id: resultId,
+    timestamp: new Date(ts).toISOString(),
+    event_id: pipelineResult.event?.event_id || null,
+    intent_id: pipelineResult.intent?.intent_id || null,
+    intent_status: pipelineResult.intent?.status || null,
+    deduplicated: pipelineResult.deduplicated === true,
+    payload: {
+      source: payload.source,
+      category: payload.category,
+      repo: payload.repo || null,
+      ref: payload.ref || null,
+    },
+    route: routed
+      ? {
+          matched: true,
+          triaged: routed.triaged === true,
+          approved: routed.approved === true,
+          planned: routed.planned === true,
+          started: routed.started === true,
+          auto_start: routed.auto_start === true || routed.started === true,
+          preferred_role: routed.preferred_role || null,
+          run_id: routed.run_id || null,
+          role: routed.role || null,
+        }
+      : { matched: false },
+    errors: errors.length > 0 ? errors : [],
+  };
+
+  const dir = join(root, '.agentxchain', 'watch-results');
+  mkdirSync(dir, { recursive: true });
+  const resultPath = join(dir, `${resultId}.json`);
+  safeWriteJson(resultPath, record);
+
+  return { result_id: resultId, result_path: resultPath };
+}
+
+function interpolateCharter(template, signal) {
+  if (!template || typeof template !== 'string') return template || 'Watch event intake';
+  if (!signal || typeof signal !== 'object') return template;
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    const value = signal[key];
+    return value !== undefined && value !== null ? String(value) : `{{${key}}}`;
+  });
+}