agentxchain 2.127.0 → 2.129.0

package/src/commands/validate.js

@@ -1,34 +1,96 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
 import chalk from 'chalk';
-import { loadConfig, loadProjectContext } from '../lib/config.js';
+import { findProjectRoot, loadConfig, loadProjectContext } from '../lib/config.js';
 import { validateGovernedProject, validateProject } from '../lib/validation.js';
 import { getGovernedVersionSurface, formatGovernedVersionLabel } from '../lib/protocol-version.js';
+import { detectConfigVersion, loadNormalizedConfig } from '../lib/normalized-config.js';
 
 export async function validateCommand(opts) {
+  const root = findProjectRoot(process.cwd());
+  if (!root) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const mode = opts.mode || 'full';
+  let rawConfig;
+  try {
+    rawConfig = JSON.parse(readFileSync(join(root, 'agentxchain.json'), 'utf8'));
+  } catch (err) {
+    console.log(chalk.red(`agentxchain.json is invalid JSON: ${err.message}`));
+    process.exit(1);
+  }
+
+  if (detectConfigVersion(rawConfig) === 4) {
+    const normalized = loadNormalizedConfig(rawConfig, root);
+    const validation = normalized.ok
+      ? validateGovernedProject(root, rawConfig, normalized.normalized, {
+          mode,
+          expectedAgent: opts.agent || null,
+        })
+      : {
+          ok: false,
+          mode,
+          errors: normalized.errors,
+          warnings: normalized.warnings || [],
+        };
+    const governedVersionSurface = getGovernedVersionSurface(rawConfig);
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ...validation,
+        protocol_mode: 'governed',
+        ...governedVersionSurface,
+        version: 4,
+      }, null, 2));
+    } else {
+      console.log('');
+      console.log(chalk.bold(`  AgentXchain Validate (${mode})`));
+      console.log(chalk.dim('  ' + '─'.repeat(44)));
+      console.log(chalk.dim(`  Root: ${root}`));
+      console.log(chalk.dim(`  Protocol: governed (${formatGovernedVersionLabel(rawConfig)})`));
+      console.log('');
+
+      if (validation.ok) {
+        console.log(chalk.green('  ✓ Validation passed.'));
+      } else {
+        console.log(chalk.red(`  ✗ Validation failed (${validation.errors.length} errors).`));
+      }
+
+      if (validation.errors.length > 0) {
+        console.log('');
+        console.log(chalk.red('  Errors:'));
+        for (const e of validation.errors) console.log(`    - ${e}`);
+      }
+
+      if (validation.warnings.length > 0) {
+        console.log('');
+        console.log(chalk.yellow('  Warnings:'));
+        for (const w of validation.warnings) console.log(`    - ${w}`);
+      }
+      console.log('');
+    }
+
+    if (!validation.ok) process.exit(1);
+    return;
+  }
+
   const context = loadProjectContext();
   if (!context) {
     console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
     process.exit(1);
   }
 
-  const mode = opts.mode || 'full';
-  const validation = context.config.protocol_mode === 'governed'
-    ? validateGovernedProject(context.root, context.rawConfig, context.config, {
-        mode,
-        expectedAgent: opts.agent || null,
-      })
-    : validateProject(context.root, loadConfig()?.config || context.rawConfig, {
-        mode,
-        expectedAgent: opts.agent || null,
-      });
+  const validation = validateProject(context.root, loadConfig()?.config || context.rawConfig, {
+    mode,
+    expectedAgent: opts.agent || null,
+  });
 
   if (opts.json) {
-    const governedVersionSurface = context.config.protocol_mode === 'governed'
-      ? getGovernedVersionSurface(context.rawConfig)
-      : {};
     console.log(JSON.stringify({
       ...validation,
       protocol_mode: context.config.protocol_mode,
-      ...governedVersionSurface,
       version: context.version,
     }, null, 2));
   } else {
@@ -36,11 +98,7 @@ export async function validateCommand(opts) {
     console.log(chalk.bold(`  AgentXchain Validate (${mode})`));
     console.log(chalk.dim('  ' + '─'.repeat(44)));
     console.log(chalk.dim(`  Root: ${context.root}`));
-    if (context.config.protocol_mode === 'governed') {
-      console.log(chalk.dim(`  Protocol: ${context.config.protocol_mode} (${formatGovernedVersionLabel(context.rawConfig)})`));
-    } else {
-      console.log(chalk.dim(`  Protocol: ${context.config.protocol_mode} (v${context.version})`));
-    }
+    console.log(chalk.dim(`  Protocol: ${context.config.protocol_mode} (v${context.version})`));
     console.log('');
 
     if (validation.ok) {

package/src/lib/adapters/local-cli-adapter.js

@@ -278,7 +278,13 @@ function resolveCommand(runtime, fullPrompt) {
 
   // Shape 1: command is an array
   if (Array.isArray(runtime.command)) {
-    const [cmd, ...rest] = runtime.command;
+    // Normalize: if the first element contains spaces (e.g., ["echo test"]), split it
+    // into binary + args. Only the first element is split — later elements may contain
+    // legitimate spaces (e.g., script text for `node -e "..."`).
+    const first = runtime.command[0] || '';
+    const headParts = typeof first === 'string' && first.includes(' ') ? first.split(/\s+/) : [first];
+    const [cmd, ...headArgs] = headParts;
+    const rest = [...headArgs, ...runtime.command.slice(1)];
     const args = transport === 'argv'
       ? rest.map(arg => arg === '{prompt}' ? fullPrompt : arg)
       : rest.filter(arg => arg !== '{prompt}');

package/src/lib/cli-version.js

@@ -0,0 +1,106 @@
+import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'));
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;
+
+export const CURRENT_CLI_VERSION = pkg.version;
+
+export function normalizeCliVersion(version) {
+  if (typeof version !== 'string') return null;
+  const trimmed = version.trim();
+  const match = SEMVER_RE.exec(trimmed);
+  if (!match) return null;
+  return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
+}
+
+export function compareCliVersions(left, right) {
+  const a = normalizeCliVersion(left);
+  const b = normalizeCliVersion(right);
+  if (!a || !b) return null;
+
+  const aParts = a.split('.').map(Number);
+  const bParts = b.split('.').map(Number);
+
+  for (let i = 0; i < 3; i += 1) {
+    if (aParts[i] > bParts[i]) return 1;
+    if (aParts[i] < bParts[i]) return -1;
+  }
+  return 0;
+}
+
+export function getPublishedDocsMinimumCliVersion() {
+  const envOverride = normalizeCliVersion(process.env.AGENTXCHAIN_DOCS_MIN_VERSION || '');
+  if (envOverride) {
+    return {
+      version: envOverride,
+      source: 'env',
+    };
+  }
+
+  try {
+    const stdout = execFileSync('npm', ['view', 'agentxchain', 'version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 3000,
+    }).trim();
+    const published = normalizeCliVersion(stdout);
+    if (!published) return null;
+    return {
+      version: published,
+      source: 'npm',
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function getCliVersionHealth() {
+  const current = normalizeCliVersion(CURRENT_CLI_VERSION);
+  const docsFloor = getPublishedDocsMinimumCliVersion();
+  if (!docsFloor) {
+    return {
+      current_version: current,
+      docs_min_cli_version: null,
+      status: 'unknown',
+      source: null,
+      stale: false,
+      detail: 'Could not verify the published docs CLI floor.',
+    };
+  }
+
+  const compare = compareCliVersions(current, docsFloor.version);
+  if (compare === null) {
+    return {
+      current_version: current,
+      docs_min_cli_version: docsFloor.version,
+      status: 'unknown',
+      source: docsFloor.source,
+      stale: false,
+      detail: 'Could not compare CLI versions.',
+    };
+  }
+
+  if (compare < 0) {
+    return {
+      current_version: current,
+      docs_min_cli_version: docsFloor.version,
+      status: 'stale',
+      source: docsFloor.source,
+      stale: true,
+      detail: `Public docs target agentxchain >= ${docsFloor.version}, but this CLI is ${current}. Upgrade with npm/Homebrew or use npx --yes -p agentxchain@latest -c "agentxchain doctor".`,
+    };
+  }
+
+  return {
+    current_version: current,
+    docs_min_cli_version: docsFloor.version,
+    status: 'ok',
+    source: docsFloor.source,
+    stale: false,
+    detail: `Running ${current}; published docs floor is ${docsFloor.version}.`,
+  };
+}

package/src/lib/connector-probe.js

@@ -9,6 +9,36 @@ import {
 const PROBEABLE_RUNTIME_TYPES = new Set(['local_cli', 'api_proxy', 'mcp', 'remote_agent']);
 const DEFAULT_TIMEOUT_MS = 8_000;
 
+/**
+ * Known local CLI tools and their authoritative-mode flags.
+ * Each entry maps a binary name pattern to the flag required for true
+ * unattended authoritative writes and any flags that look similar but
+ * do NOT grant full authority.
+ */
+const KNOWN_CLI_AUTHORITY_FLAGS = [
+  {
+    binary: 'claude',
+    authoritative_flag: '--dangerously-skip-permissions',
+    weak_flags: [],
+    label: 'Claude Code',
+  },
+  {
+    binary: 'codex',
+    authoritative_flag: '--dangerously-bypass-approvals-and-sandbox',
+    weak_flags: ['--full-auto'],
+    label: 'OpenAI Codex CLI',
+  },
+];
+
+/**
+ * Known prompt transport requirements per CLI binary.
+ * Maps binary name to expected transport.
+ */
+const KNOWN_CLI_TRANSPORTS = {
+  claude: 'stdin',
+  codex: 'argv',
+};
+
 function formatCommand(command, args = []) {
   if (Array.isArray(command)) {
     return command.join(' ');
@@ -38,7 +68,9 @@ function formatTarget(runtime) {
 
 function commandHead(runtime) {
   if (Array.isArray(runtime?.command)) {
-    return runtime.command[0] || null;
+    const first = runtime.command[0] || null;
+    if (first && first.includes(' ')) return first.split(/\s+/)[0];
+    return first;
   }
   if (typeof runtime?.command === 'string' && runtime.command.trim()) {
     return runtime.command.trim().split(/\s+/)[0];
@@ -272,8 +304,103 @@ async function probeHttpRuntime(runtimeId, runtime, timeoutMs) {
   };
 }
 
+/**
+ * Analyze a local_cli runtime's command shape for authority-intent alignment.
+ * Returns an array of warnings (may be empty).
+ *
+ * @param {string} runtimeId
+ * @param {object} runtime - runtime config entry
+ * @param {object} roles - map of roleId → role config (to determine write_authority)
+ * @returns {{ warnings: Array<{probe_kind: string, level: string, detail: string, fix?: string}> }}
+ */
+function analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles) {
+  const warnings = [];
+  if (runtime?.type !== 'local_cli') return { warnings };
+
+  const commandTokens = normalizeCommandTokens(runtime);
+  if (commandTokens.length === 0) return { warnings };
+
+  const binaryName = commandTokens[0].toLowerCase();
+  const allFlags = commandTokens.slice(1).join(' ');
+
+  // Find roles that use this runtime
+  const boundRoles = Object.entries(roles || {})
+    .filter(([, role]) => role?.runtime === runtimeId)
+    .map(([roleId, role]) => ({ roleId, write_authority: role.write_authority }));
+
+  if (boundRoles.length === 0) return { warnings };
+
+  const authoritativeRoles = boundRoles.filter((r) => r.write_authority === 'authoritative');
+
+  // Check known CLI authority flags
+  const knownCli = KNOWN_CLI_AUTHORITY_FLAGS.find((entry) => binaryName === entry.binary || binaryName.endsWith(`/${entry.binary}`));
+  if (knownCli && authoritativeRoles.length > 0) {
+    const hasAuthFlag = commandTokens.some((token) => token === knownCli.authoritative_flag);
+    if (!hasAuthFlag) {
+      const usesWeakFlag = knownCli.weak_flags.find((wf) => commandTokens.some((token) => token === wf));
+      const roleNames = authoritativeRoles.map((r) => r.roleId).join(', ');
+      if (usesWeakFlag) {
+        warnings.push({
+          probe_kind: 'authority_intent',
+          level: 'warn',
+          detail: `${knownCli.label} uses "${usesWeakFlag}" which does NOT grant full unattended authority — role(s) [${roleNames}] require authoritative writes`,
+          fix: `Replace "${usesWeakFlag}" with "${knownCli.authoritative_flag}" in the command array`,
+        });
+      } else {
+        warnings.push({
+          probe_kind: 'authority_intent',
+          level: 'warn',
+          detail: `${knownCli.label} command is missing "${knownCli.authoritative_flag}" — role(s) [${roleNames}] require authoritative writes but the subprocess may block on approval prompts`,
+          fix: `Add "${knownCli.authoritative_flag}" to the command array`,
+        });
+      }
+    }
+  }
+
+  // Prompt transport validation
+  const transport = runtime.prompt_transport || 'dispatch_bundle_only';
+  const knownTransport = KNOWN_CLI_TRANSPORTS[binaryName];
+
+  if (transport === 'argv' && !commandTokens.some((token) => token.includes('{prompt}'))) {
+    warnings.push({
+      probe_kind: 'transport_intent',
+      level: 'warn',
+      detail: `prompt_transport is "argv" but no {prompt} placeholder found in command — the prompt will not be delivered`,
+      fix: `Add a "{prompt}" placeholder to the command array, e.g. ["${binaryName}", ..., "{prompt}"]`,
+    });
+  }
+
+  if (knownTransport && transport !== knownTransport && transport !== 'dispatch_bundle_only') {
+    const transportLabel = knownCli ? knownCli.label : binaryName;
+    warnings.push({
+      probe_kind: 'transport_intent',
+      level: 'warn',
+      detail: `${transportLabel} typically uses "${knownTransport}" transport, but this runtime is configured with "${transport}"`,
+      fix: `Set prompt_transport to "${knownTransport}" or "dispatch_bundle_only"`,
+    });
+  }
+
+  return { warnings };
+}
+
+/**
+ * Normalize a runtime's command field into an array of tokens.
+ */
+function normalizeCommandTokens(runtime) {
+  if (Array.isArray(runtime?.command)) {
+    return runtime.command.flatMap((element) =>
+      typeof element === 'string' ? element.trim().split(/\s+/).filter(Boolean) : []
+    );
+  }
+  if (typeof runtime?.command === 'string' && runtime.command.trim()) {
+    return runtime.command.trim().split(/\s+/).filter(Boolean);
+  }
+  return [];
+}
+
 export async function probeConnectorRuntime(runtimeId, runtime, options = {}) {
   const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
+  const roles = options.roles || null;
 
   if (!runtime || !PROBEABLE_RUNTIME_TYPES.has(runtime.type)) {
     return {
@@ -287,7 +414,19 @@ export async function probeConnectorRuntime(runtimeId, runtime, options = {}) {
   }
 
   if (runtime.type === 'local_cli') {
-    return probeLocalCommand(runtimeId, runtime, 'command_presence');
+    const result = await probeLocalCommand(runtimeId, runtime, 'command_presence');
+    // Add authority-intent and transport analysis when roles are available
+    if (roles) {
+      const { warnings } = analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles);
+      if (warnings.length > 0) {
+        result.authority_warnings = warnings;
+        // Promote result level to 'warn' if binary is present but authority intent is wrong
+        if (result.level === 'pass') {
+          result.level = 'warn';
+        }
+      }
+    }
+    return result;
   }
 
   if (runtime.type === 'api_proxy') {
@@ -308,6 +447,7 @@ export async function probeConfiguredConnectors(config, options = {}) {
   const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
   const requestedRuntimeId = options.runtimeId || null;
   const onProbeStart = typeof options.onProbeStart === 'function' ? options.onProbeStart : null;
+  const roles = config?.roles || null;
 
   const runtimeEntries = Object.entries(config?.runtimes || {})
     .filter(([, runtime]) => PROBEABLE_RUNTIME_TYPES.has(runtime?.type))
@@ -324,30 +464,33 @@ export async function probeConfiguredConnectors(config, options = {}) {
     }
     const [runtimeId, runtime] = match;
     onProbeStart?.(runtimeId, runtime);
-    const connector = await probeConnectorRuntime(runtimeId, runtime, { timeoutMs });
+    const connector = await probeConnectorRuntime(runtimeId, runtime, { timeoutMs, roles });
     return summarizeResults([connector], timeoutMs);
   }
 
   const connectors = [];
   for (const [runtimeId, runtime] of runtimeEntries) {
     onProbeStart?.(runtimeId, runtime);
-    connectors.push(await probeConnectorRuntime(runtimeId, runtime, { timeoutMs }));
+    connectors.push(await probeConnectorRuntime(runtimeId, runtime, { timeoutMs, roles }));
   }
   return summarizeResults(connectors, timeoutMs);
 }
 
 function summarizeResults(connectors, timeoutMs) {
   const failCount = connectors.filter((item) => item.level === 'fail').length;
+  const warnCount = connectors.filter((item) => item.level === 'warn').length;
   const passCount = connectors.filter((item) => item.level === 'pass').length;
+  const overall = failCount > 0 ? 'fail' : warnCount > 0 ? 'warn' : 'pass';
   return {
     ok: failCount === 0,
     exitCode: failCount === 0 ? 0 : 1,
-    overall: failCount === 0 ? 'pass' : 'fail',
+    overall,
     timeout_ms: timeoutMs,
     pass_count: passCount,
+    warn_count: warnCount,
     fail_count: failCount,
     connectors,
   };
 }
 
-export { DEFAULT_TIMEOUT_MS, PROBEABLE_RUNTIME_TYPES };
+export { DEFAULT_TIMEOUT_MS, PROBEABLE_RUNTIME_TYPES, KNOWN_CLI_AUTHORITY_FLAGS, KNOWN_CLI_TRANSPORTS, analyzeLocalCliAuthorityIntent, normalizeCommandTokens };

package/src/lib/continuous-run.js

@@ -9,7 +9,7 @@
  * Decision: DEC-VISION-CONTINUOUS-001
  */
 
-import { existsSync, readFileSync, readdirSync, mkdirSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { resolveVisionPath, deriveVisionCandidates } from './vision-reader.js';
@@ -17,8 +17,9 @@ import {
   recordEvent,
   triageIntent,
   approveIntent,
-  planIntent,
-  startIntent,
+  findNextDispatchableIntent,
+  prepareIntentForDispatch,
+  consumeNextApprovedIntent,
   resolveIntent,
 } from './intake.js';
 import { loadProjectState } from './config.js';
@@ -112,40 +113,6 @@ function isBlockedContinuousExecution(execution) {
 // Intake queue check
 // ---------------------------------------------------------------------------
 
-/**
- * Find the next approved or planned intent in the intake queue.
- *
- * @param {string} root
- * @returns {{ ok: boolean, intentId?: string, status?: string }}
- */
-export function findNextQueuedIntent(root) {
-  const intentsDir = join(root, '.agentxchain', 'intake', 'intents');
-  if (!existsSync(intentsDir)) return { ok: false };
-
-  const files = readdirSync(intentsDir).filter(f => f.endsWith('.json') && !f.startsWith('.tmp-'));
-
-  // Priority order: planned > approved (planned is closer to execution)
-  let bestPlanned = null;
-  let bestApproved = null;
-
-  for (const file of files) {
-    try {
-      const intent = JSON.parse(readFileSync(join(intentsDir, file), 'utf8'));
-      if (intent.status === 'planned' && !bestPlanned) {
-        bestPlanned = { intentId: intent.intent_id, status: 'planned' };
-      } else if (intent.status === 'approved' && !bestApproved) {
-        bestApproved = { intentId: intent.intent_id, status: 'approved' };
-      }
-    } catch {
-      // skip corrupt
-    }
-  }
-
-  if (bestPlanned) return { ok: true, ...bestPlanned };
-  if (bestApproved) return { ok: true, ...bestApproved };
-  return { ok: false };
-}
-
 function readIntent(root, intentId) {
   const intentPath = join(root, '.agentxchain', 'intake', 'intents', `${intentId}.json`);
   if (!existsSync(intentPath)) return null;
@@ -166,50 +133,8 @@ function buildContinuousProvenance(intentId, options = {}) {
   };
 }
 
-function prepareIntentForRun(root, intentId, options = {}) {
-  let intent = readIntent(root, intentId);
-  if (!intent) {
-    return { ok: false, error: `intent ${intentId} not found` };
-  }
-
-  if (intent.status === 'approved') {
-    const planned = planIntent(root, intentId);
-    if (!planned.ok) {
-      return { ok: false, error: `plan failed: ${planned.error}` };
-    }
-    intent = planned.intent;
-  }
-
-  if (intent.status === 'planned') {
-    const started = startIntent(root, intentId, {
-      allowTerminalRestart: true,
-      provenance: options.provenance,
-    });
-    if (!started.ok) {
-      return { ok: false, error: `start failed: ${started.error}` };
-    }
-    intent = started.intent;
-    return {
-      ok: true,
-      intent,
-      runId: started.run_id,
-      turnId: started.turn_id,
-    };
-  }
-
-  if (intent.status === 'executing') {
-    return {
-      ok: true,
-      intent,
-      runId: intent.target_run || null,
-      turnId: intent.target_turn || null,
-    };
-  }
-
-  return {
-    ok: false,
-    error: `intent ${intentId} is in unsupported status "${intent.status}" for continuous execution`,
-  };
+export function findNextQueuedIntent(root) {
+  return findNextDispatchableIntent(root);
 }
 
 // ---------------------------------------------------------------------------
@@ -420,7 +345,7 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
   }
 
   // Step 1: Check intake queue for pending work
-  const queued = findNextQueuedIntent(root);
+  const queued = findNextDispatchableIntent(root);
   let targetIntentId = null;
   let visionObjective = null;
 
@@ -467,7 +392,10 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
     trigger: visionObjective ? 'vision_scan' : 'intake',
     triggerReason: visionObjective || readIntent(root, targetIntentId)?.charter || null,
   });
-  const preparedIntent = prepareIntentForRun(root, targetIntentId, { provenance });
+  const preparedIntent = prepareIntentForDispatch(root, targetIntentId, {
+    allowTerminalRestart: true,
+    provenance,
+  });
   if (!preparedIntent.ok) {
     log(`Continuous start error: ${preparedIntent.error}`);
     session.status = 'failed';
@@ -476,7 +404,7 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
   }
 
   // Execute the governed run
-  session.current_run_id = preparedIntent.runId;
+  session.current_run_id = preparedIntent.run_id;
   session.current_vision_objective = visionObjective || preparedIntent.intent?.charter || null;
   session.status = 'running';
   writeContinuousSession(root, session);
@@ -497,12 +425,12 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
       status: 'failed',
       action: 'run_failed',
       stop_reason: err.message,
-      run_id: preparedIntent.runId || null,
+      run_id: preparedIntent.run_id || null,
       intent_id: targetIntentId,
     };
   }
 
-  session.current_run_id = execution.result?.state?.run_id || preparedIntent.runId || null;
+  session.current_run_id = execution.result?.state?.run_id || preparedIntent.run_id || null;
   session.cumulative_spent_usd = (session.cumulative_spent_usd || 0) + getExecutionRunSpentUsd(execution);
 
   const stopReason = execution.result?.stop_reason;

package/src/lib/dispatch-bundle.js

@@ -16,8 +16,10 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { execSync } from 'child_process';
 import { getActiveTurn, getActiveTurns } from './governed-state.js';
 import { renderInheritedContextMarkdown } from './run-context-inheritance.js';
+import { isOperationalPath } from './repo-observer.js';
 import { renderRepoDecisionsMarkdown } from './repo-decisions.js';
 import {
   DISPATCH_INDEX_PATH,
@@ -83,6 +85,25 @@ export function writeDispatchBundle(root, state, config, opts = {}) {
   const bundleDir = join(root, getDispatchTurnDir(turn.turn_id));
   const warnings = [...(opts.warnings || [])];
 
+  // BUG-5: Warn operator about dirty workspace files at dispatch time
+  try {
+    const statusOutput = execSync('git status --porcelain', { cwd: root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    if (statusOutput) {
+      const dirtyFiles = statusOutput.split('\n').map(l => l.slice(3).trim()).filter(Boolean);
+      const nonOperationalDirty = dirtyFiles.filter(f => !isOperationalPath(f));
+      if (nonOperationalDirty.length > 0) {
+        const baseline = turn.baseline;
+        const snapshotKeys = baseline?.dirty_snapshot ? Object.keys(baseline.dirty_snapshot) : [];
+        const unsnapshotted = nonOperationalDirty.filter(f => !snapshotKeys.includes(f));
+        if (unsnapshotted.length > 0) {
+          warnings.push(
+            `Workspace has ${unsnapshotted.length} uncommitted file(s) not in the dispatch baseline: ${unsnapshotted.slice(0, 5).join(', ')}${unsnapshotted.length > 5 ? '...' : ''}. These will be excluded from files_changed validation. If the subprocess modifies them, add them to files_changed.`,
+          );
+        }
+      }
+    }
+  } catch { /* non-fatal — skip if git unavailable */ }
+
   // Clear and recreate only the targeted turn bundle
   try {
     rmSync(bundleDir, { recursive: true, force: true });
@@ -311,6 +332,24 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('');
   }
 
+  if (turn.intake_context) {
+    lines.push('### Active Injected Intent — respond to this as your primary charter');
+    lines.push('');
+    if (turn.intake_context.charter) {
+      lines.push(turn.intake_context.charter);
+      lines.push('');
+    }
+    if (Array.isArray(turn.intake_context.acceptance_contract) && turn.intake_context.acceptance_contract.length > 0) {
+      lines.push('Acceptance contract:');
+      turn.intake_context.acceptance_contract.forEach((requirement, index) => {
+        lines.push(`${index + 1}. ${requirement}`);
+      });
+      lines.push('');
+    }
+    lines.push('You must explicitly address every acceptance item in your turn summary, artifacts, or verification evidence. Do not treat this as background context.');
+    lines.push('');
+  }
+
   // Retry context
   if (turn.attempt > 1 && turn.last_rejection) {
     lines.push('## Previous Attempt Failed');