agentxchain 2.155.73 → 2.157.0

package/src/lib/stream-json-cost-parser.js

@@ -0,0 +1,169 @@
+/**
+ * Stream-JSON cost parser — extracts usage/cost metadata from Claude Code's
+ * stream-json NDJSON stdout output.
+ *
+ * Claude Code with `--output-format stream-json --verbose` emits newline-
+ * delimited JSON events.  The final `result` event contains a `usage` object
+ * with `input_tokens`, `output_tokens`, and optionally cache token counts,
+ * plus a top-level `cost_usd` and `model` field.
+ *
+ * This parser accumulates stdout chunks, splits by newline, parses each
+ * complete line as JSON, and stores the last `result` event's cost data.
+ *
+ * Resilience guarantees:
+ *   - Partial JSON lines are buffered until the next newline arrives.
+ *   - Non-JSON lines are silently skipped (no throw, no error log).
+ *   - Multiple `result` events: last one wins.
+ *   - Missing `usage` in a `result` event: getResult() returns null.
+ */
+
+// Claude-specific bundled cost rates (USD per million tokens).
+// Duplicated from api-proxy-adapter.js for this module's use only — DEC-004
+// defers extraction to a shared module.
+const CLAUDE_COST_RATES = {
+  'claude-sonnet-4-6': { input_per_1m: 3.00, output_per_1m: 15.00 },
+  'claude-opus-4-6': { input_per_1m: 5.00, output_per_1m: 25.00 },
+  'claude-haiku-4-5-20251001': { input_per_1m: 1.00, output_per_1m: 5.00 },
+};
+
+/**
+ * Resolve cost rates for a model. Checks operator-supplied overrides first,
+ * then falls back to the bundled Claude rates.
+ *
+ * @param {string} model
+ * @param {object} [config]
+ * @returns {{ input_per_1m: number, output_per_1m: number } | null}
+ */
+export function getClaudeCostRates(model, config) {
+  const operatorRates = config?.budget?.cost_rates;
+  if (operatorRates && typeof operatorRates === 'object' && operatorRates[model]) {
+    const r = operatorRates[model];
+    if (Number.isFinite(r.input_per_1m) && Number.isFinite(r.output_per_1m)) {
+      return r;
+    }
+  }
+  return CLAUDE_COST_RATES[model] || null;
+}
+
+/**
+ * @typedef {Object} StreamJsonCostResult
+ * @property {number} input_tokens
+ * @property {number} output_tokens
+ * @property {number|null} cost_usd - Claude Code's self-reported cost (if present)
+ * @property {string|null} model - Model identifier for rate lookup
+ * @property {number|null} cache_creation_input_tokens
+ * @property {number|null} cache_read_input_tokens
+ */
+
+/**
+ * Create a stateful parser that accumulates stream-json chunks and extracts
+ * the final result event containing usage metadata.
+ *
+ * @returns {{ push(chunk: string): void, getResult(): StreamJsonCostResult | null }}
+ */
+export function createStreamJsonCostParser() {
+  let buffer = '';
+  /** @type {StreamJsonCostResult | null} */
+  let lastResult = null;
+
+  return {
+    /**
+     * Feed a stdout chunk into the parser.
+     * @param {string} chunk
+     */
+    push(chunk) {
+      buffer += chunk;
+      const lines = buffer.split('\n');
+      // Last element is either empty (line ended with \n) or a partial line
+      buffer = lines.pop() || '';
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+
+        let parsed;
+        try {
+          parsed = JSON.parse(trimmed);
+        } catch {
+          // Non-JSON line (tool output, diagnostic text) — skip silently
+          continue;
+        }
+
+        if (
+          parsed &&
+          typeof parsed === 'object' &&
+          parsed.type === 'result' &&
+          parsed.usage &&
+          typeof parsed.usage === 'object' &&
+          Number.isFinite(parsed.usage.input_tokens) &&
+          Number.isFinite(parsed.usage.output_tokens)
+        ) {
+          lastResult = {
+            input_tokens: parsed.usage.input_tokens,
+            output_tokens: parsed.usage.output_tokens,
+            cost_usd: typeof parsed.cost_usd === 'number' && Number.isFinite(parsed.cost_usd)
+              ? parsed.cost_usd
+              : null,
+            model: typeof parsed.model === 'string' ? parsed.model : null,
+            cache_creation_input_tokens: Number.isFinite(parsed.usage.cache_creation_input_tokens)
+              ? parsed.usage.cache_creation_input_tokens
+              : null,
+            cache_read_input_tokens: Number.isFinite(parsed.usage.cache_read_input_tokens)
+              ? parsed.usage.cache_read_input_tokens
+              : null,
+          };
+        }
+      }
+    },
+
+    /**
+     * Return the extracted cost data, or null if no valid result event was found.
+     * @returns {StreamJsonCostResult | null}
+     */
+    getResult() {
+      return lastResult;
+    },
+  };
+}
+
+/**
+ * Build a cost object from parsed stream-json data for turn-result enrichment.
+ *
+ * @param {StreamJsonCostResult} parsedCost
+ * @param {object} [config] - normalized config (for operator cost_rates overrides)
+ * @returns {{ input_tokens: number, output_tokens: number, usd: number, source: string, model?: string, cache_creation_input_tokens?: number, cache_read_input_tokens?: number }}
+ */
+export function buildCostFromStreamJson(parsedCost, config) {
+  const cost = {
+    input_tokens: parsedCost.input_tokens,
+    output_tokens: parsedCost.output_tokens,
+    source: 'stream_json',
+  };
+
+  // Prefer Claude Code's own cost_usd when available
+  if (typeof parsedCost.cost_usd === 'number' && Number.isFinite(parsedCost.cost_usd)) {
+    cost.usd = Math.round(parsedCost.cost_usd * 1000) / 1000;
+  } else if (parsedCost.model) {
+    const rates = getClaudeCostRates(parsedCost.model, config);
+    if (rates) {
+      cost.usd = Math.round(
+        ((parsedCost.input_tokens / 1_000_000) * rates.input_per_1m +
+         (parsedCost.output_tokens / 1_000_000) * rates.output_per_1m) * 1000
+      ) / 1000;
+    } else {
+      cost.usd = 0;
+    }
+  } else {
+    cost.usd = 0;
+  }
+
+  if (parsedCost.model) cost.model = parsedCost.model;
+  if (parsedCost.cache_creation_input_tokens != null) {
+    cost.cache_creation_input_tokens = parsedCost.cache_creation_input_tokens;
+  }
+  if (parsedCost.cache_read_input_tokens != null) {
+    cost.cache_read_input_tokens = parsedCost.cache_read_input_tokens;
+  }
+
+  return cost;
+}

package/src/lib/turn-checkpoint.js

@@ -352,6 +352,27 @@ export function checkpointAcceptedTurn(root, opts = {}) {
   }
 
   const entry = resolved.entry;
+
+  // Proposed turns materialize their files under .agentxchain/proposed/<turn_id>/, never
+  // the workspace — there is nothing to `git add` until `proposal apply` promotes them.
+  // Attempting to stage the declared workspace paths fails with "pathspec did not match",
+  // so checkpoint cleanly skips proposed/patch turns.
+  if (
+    entry?.artifact
+    && typeof entry.artifact === 'object'
+    && !Array.isArray(entry.artifact)
+    && entry.artifact.type === 'patch'
+    && typeof entry.artifact.ref === 'string'
+    && entry.artifact.ref.startsWith('.agentxchain/proposed/')
+  ) {
+    return {
+      ok: true,
+      skipped: true,
+      turn: entry,
+      reason: 'Proposed turn materialized under .agentxchain/proposed/; no workspace checkpoint needed until proposal apply.',
+    };
+  }
+
   const supplementalFilesChanged = entry.checkpoint_sha
     ? recoverSupplementalCheckpointFiles(root, entry)
     : [];

package/src/lib/turn-result-validator.js

@@ -737,6 +737,16 @@ function validateArtifact(tr, config, state = null) {
         `Role "${tr.role}" completed an implementation turn without product code changes in files_changed. ` +
         'Implementation-phase completion requires at least one non-planning, non-review repo path; planning artifacts alone are not sufficient.'
       );
+    } else if (productFiles.every(f => isTestPath(f))) {
+      // Work-substance signal: an implementation turn that changed ONLY test files produced
+      // no implementation source. That is legitimate for acceptance/verification objectives,
+      // but thin for an "implement X" objective — surface it for QA/operator review instead
+      // of silently accepting (this test-only pattern slipped through QA during dogfooding).
+      warnings.push(
+        `Role "${tr.role}" completed an implementation turn that changed only test files ` +
+        `(${productFiles.join(', ')}) with no implementation source. This is valid for acceptance or ` +
+        'verification work; if the objective was to implement behavior, review whether the turn is test-only before accepting.'
+      );
     }
   }
 
@@ -792,6 +802,16 @@ function isProductChangePath(filePath) {
     && !filePath.startsWith('.agentxchain/staging/');
 }
 
+// A test/spec file path — used to flag implementation turns that produced only tests
+// (no implementation source) so test-only work is reviewed rather than silently accepted.
+function isTestPath(filePath) {
+  if (typeof filePath !== 'string') {
+    return false;
+  }
+  return /(^|\/)(tests?|__tests__|spec)\//.test(filePath)
+    || /\.(test|spec)\.[cm]?[jt]sx?$/.test(filePath);
+}
+
 function hasCheckpointableProducedFiles(tr) {
   return Array.isArray(tr.verification?.produced_files)
     && tr.verification.produced_files.some((entry) => (
@@ -1523,6 +1543,11 @@ export function normalizeTurnResult(tr, config, context = {}) {
     && (
       context.forceReviewArtifact
       || hasExplicitNoEditLifecycleSignal
+      // review_only roles (PM/QA) legitimately produce no-edit reviews — an empty
+      // workspace from a COMPLETED review_only turn normalizes to a review. Authoritative
+      // /code-writing roles claiming a completed workspace artifact with no files stay
+      // fail-closed, and non-completed (blocked/failed) turns never normalize (BUG-78).
+      || (isReviewOnly && normalized.status === 'completed')
       || (normalized.status === 'needs_human' && normalized.proposed_next_role === 'human')
     )
   ) {

package/src/lib/validation.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { validateStagedTurnResult, STAGING_PATH } from './turn-result-validator.js';
 import { getActiveTurn } from './governed-state.js';
+import { getTurnStagingResultPath } from './turn-paths.js';
 import {
   validateGovernedProjectTemplate,
   validateGovernedTemplateRegistry,
@@ -191,11 +192,18 @@ export function validateGovernedProject(root, rawConfig, config, opts = {}) {
 
   // ── Staged turn-result validation (the acceptance boundary) ─────────────
   if (mode === 'turn' && state) {
-    const stagingAbs = join(root, STAGING_PATH);
+    // RB-12: prefer the turn-scoped staging path for the active turn; the shared
+    // legacy path is only a fallback. Reading the legacy path unconditionally
+    // made `validate --mode turn` look at the wrong file and falsely report a
+    // missing turn result for turns staged at the turn-scoped path.
+    const activeTurn = getActiveTurn(state) || state.current_turn || null;
+    const turnScoped = activeTurn?.turn_id ? getTurnStagingResultPath(activeTurn.turn_id) : null;
+    const stagingRel = (turnScoped && existsSync(join(root, turnScoped))) ? turnScoped : STAGING_PATH;
+    const stagingAbs = join(root, stagingRel);
     if (!existsSync(stagingAbs)) {
-      warnings.push(`No staged turn result found at ${STAGING_PATH}. Agent has not yet emitted a turn result.`);
+      warnings.push(`No staged turn result found at ${stagingRel}. Agent has not yet emitted a turn result.`);
     } else {
-      const turnValidation = validateStagedTurnResult(root, state, config);
+      const turnValidation = validateStagedTurnResult(root, state, config, { stagingPath: stagingRel });
       if (!turnValidation.ok) {
         errors.push(
           `Staged turn result failed at stage "${turnValidation.stage}" (${turnValidation.error_class}):`,

package/src/lib/verification-replay.js

@@ -8,7 +8,7 @@ import { isOperationalPath } from './repo-observer.js';
 
 export const DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS = 30_000;
 
-export function replayVerificationMachineEvidence({ root, verification, timeoutMs = DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS }) {
+export function replayVerificationMachineEvidence({ root, verification, timeoutMs = DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS, allowCommandExecution = false }) {
   const verifiedAt = new Date().toISOString();
   const machineEvidence = Array.isArray(verification?.machine_evidence)
     ? verification.machine_evidence
@@ -28,6 +28,27 @@ export function replayVerificationMachineEvidence({ root, verification, timeoutM
     return payload;
   }
 
+  // SECURITY (verification-replay hardening): agent-declared machine_evidence
+  // commands are UNTRUSTED. Fail-safe default — they are recorded but NOT executed
+  // unless the operator has explicitly opted in (allowCommandExecution). When
+  // executed, they never run through a shell (see replayEvidenceCommand).
+  if (!allowCommandExecution) {
+    payload.overall = 'not_executed';
+    payload.reason = 'Command replay disabled: agent-declared verification commands are not executed unless explicitly enabled by the operator.';
+    payload.commands = machineEvidence.map((entry, index) => ({
+      index,
+      command: entry?.command ?? null,
+      declared_exit_code: entry?.exit_code,
+      actual_exit_code: null,
+      matched: false,
+      executed: false,
+      timed_out: false,
+      signal: null,
+      error: null,
+    }));
+    return payload;
+  }
+
   const workspaceGuard = createReplayWorkspaceGuard(root);
   try {
     payload.commands = machineEvidence.map((entry, index) => replayEvidenceCommand(root, entry, index, timeoutMs));
@@ -41,11 +62,33 @@ export function replayVerificationMachineEvidence({ root, verification, timeoutM
   return payload;
 }
 
+// SECURITY: agent-declared commands are NEVER run through a shell. The command is
+// resolved to an argv vector and executed with shell:false, so shell metacharacters
+// (; | && $() backticks globs) cannot chain, pipe, expand, or substitute. (A single
+// declared binary still runs on the host — that is gated by the explicit
+// allowCommandExecution opt-in upstream; a future sandbox/allowlist can constrain
+// which binaries are permitted.)
 export function replayEvidenceCommand(root, entry, index, timeoutMs = DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS) {
-  const result = spawnSync(entry.command, {
+  const argv = resolveEvidenceArgv(entry);
+  if (argv.length === 0) {
+    return {
+      index,
+      command: entry?.command ?? null,
+      declared_exit_code: entry?.exit_code,
+      actual_exit_code: null,
+      matched: false,
+      executed: false,
+      timed_out: false,
+      signal: null,
+      error: 'No executable command or argv vector could be resolved for this evidence entry.',
+    };
+  }
+
+  const [file, ...args] = argv;
+  const result = spawnSync(file, args, {
     cwd: root,
     encoding: 'utf8',
-    shell: true,
+    shell: false,
     timeout: timeoutMs,
     maxBuffer: 1024 * 1024,
   });
@@ -56,16 +99,94 @@ export function replayEvidenceCommand(root, entry, index, timeoutMs = DEFAULT_VE
 
   return {
     index,
-    command: entry.command,
+    command: entry.command ?? argv.join(' '),
     declared_exit_code: entry.exit_code,
     actual_exit_code: actualExitCode,
     matched: actualExitCode === entry.exit_code,
+    executed: true,
     timed_out: timedOut,
     signal: result.signal || null,
     error: errorMessage,
   };
 }
 
+// Resolve an evidence entry to an argv vector for shell-free execution.
+// Prefers a structured `argv` string array; falls back to safe-tokenizing `command`.
+export function resolveEvidenceArgv(entry) {
+  if (Array.isArray(entry?.argv) && entry.argv.length > 0 && entry.argv.every((a) => typeof a === 'string')) {
+    return entry.argv.slice();
+  }
+  if (typeof entry?.command === 'string' && entry.command.trim()) {
+    return tokenizeCommand(entry.command.trim());
+  }
+  return [];
+}
+
+// Minimal SAFE tokenizer: splits on whitespace, honoring single and double quotes
+// and backslash escapes (so e.g. `node -e "{\"ok\":true}"` keeps its escaped quotes).
+// Performs NO shell expansion — variables, globs, pipes, chaining, and command
+// substitution are preserved as literal characters, never interpreted.
+export function tokenizeCommand(command) {
+  if (typeof command !== 'string') {
+    return [];
+  }
+  const tokens = [];
+  let current = '';
+  let hasToken = false;
+  let i = 0;
+  const n = command.length;
+  while (i < n) {
+    const ch = command[i];
+    if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+      if (hasToken) {
+        tokens.push(current);
+        current = '';
+        hasToken = false;
+      }
+      i += 1;
+      continue;
+    }
+    hasToken = true;
+    if (ch === "'") {
+      // Single-quoted: literal run until the next single quote (no escapes, POSIX-style).
+      i += 1;
+      while (i < n && command[i] !== "'") {
+        current += command[i];
+        i += 1;
+      }
+      i += 1; // consume closing quote (or run off the end)
+      continue;
+    }
+    if (ch === '"') {
+      // Double-quoted: backslash escapes only the structural `"` and `\` characters.
+      i += 1;
+      while (i < n && command[i] !== '"') {
+        if (command[i] === '\\' && i + 1 < n && (command[i + 1] === '"' || command[i + 1] === '\\')) {
+          current += command[i + 1];
+          i += 2;
+        } else {
+          current += command[i];
+          i += 1;
+        }
+      }
+      i += 1; // consume closing quote (or run off the end)
+      continue;
+    }
+    if (ch === '\\' && i + 1 < n) {
+      // Bare backslash escape: take the next character literally.
+      current += command[i + 1];
+      i += 2;
+      continue;
+    }
+    current += ch;
+    i += 1;
+  }
+  if (hasToken) {
+    tokens.push(current);
+  }
+  return tokens;
+}
+
 export function summarizeVerificationReplay(payload) {
   if (!payload) {
     return null;

package/src/lib/vision-reader.js

@@ -16,6 +16,11 @@ import { join, resolve as pathResolve, isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
 
 const ROADMAP_TRACKING_ANNOTATION_PATTERN = /<!--\s*tracking\s*:[\s\S]*?-->/i;
+// RB-3: a milestone left unchecked but annotated as delivered/done/shipped is
+// already-built work — skip it so the loop derives genuinely undelivered work
+// instead of re-picking finished items. Distinct from generic comments like
+// `<!-- owner: dev -->`, which stay actionable.
+const ROADMAP_DELIVERED_ANNOTATION_PATTERN = /<!--[^>]*\b(delivered|shipped|implemented|completed|done)\b[^>]*-->/i;
 
 export function stripRoadmapTrackingAnnotations(text) {
   if (typeof text !== 'string') return '';
@@ -266,7 +271,7 @@ export function deriveRoadmapCandidates(root, roadmapPath = '.planning/ROADMAP.m
 
     const uncheckedMatch = line.match(/^\s*[-*]\s+\[\s\]\s+(.+?)\s*$/);
     if (!uncheckedMatch || !currentMilestone) continue;
-    if (ROADMAP_TRACKING_ANNOTATION_PATTERN.test(line)) continue;
+    if (ROADMAP_TRACKING_ANNOTATION_PATTERN.test(line) || ROADMAP_DELIVERED_ANNOTATION_PATTERN.test(line)) continue;
 
     const goal = stripRoadmapTrackingAnnotations(uncheckedMatch[1]);
     if (!goal) continue;
@@ -493,7 +498,7 @@ export function detectRoadmapExhaustedVisionOpen(root, visionPath, roadmapPath =
       continue;
     }
     if (currentMilestone && /^\s*[-*]\s+\[\s\]/.test(line)) {
-      if (ROADMAP_TRACKING_ANNOTATION_PATTERN.test(line)) continue;
+      if (ROADMAP_TRACKING_ANNOTATION_PATTERN.test(line) || ROADMAP_DELIVERED_ANNOTATION_PATTERN.test(line)) continue;
       hasUnchecked = true;
     }
   }