agentxchain 2.153.0 → 2.154.0

package/bin/agentxchain.js

@@ -73,6 +73,7 @@ import { injectCommand } from '../src/commands/inject.js';
 import { escalateCommand } from '../src/commands/escalate.js';
 import { acceptTurnCommand } from '../src/commands/accept-turn.js';
 import { checkpointTurnCommand } from '../src/commands/checkpoint-turn.js';
+import { reconcileStateCommand } from '../src/commands/reconcile-state.js';
 import { rejectTurnCommand } from '../src/commands/reject-turn.js';
 import { reissueTurnCommand } from '../src/commands/reissue-turn.js';
 import { proposalListCommand, proposalDiffCommand, proposalApplyCommand, proposalRejectCommand } from '../src/commands/proposal.js';
@@ -701,6 +702,12 @@ program
   .option('--turn <id>', 'Checkpoint a specific accepted turn from history')
   .action(checkpointTurnCommand);
 
+program
+  .command('reconcile-state')
+  .description('Reconcile safe operator commits into governed run state')
+  .option('--accept-operator-head', 'Accept safe fast-forward operator commits as the new governed baseline')
+  .action(reconcileStateCommand);
+
 program
   .command('reject-turn')
   .description('Reject the current governed turn result and retry or escalate')
@@ -757,6 +764,7 @@ program
   .option('--no-auto-retry-on-ghost', 'Disable bounded automatic retry for continuous-mode startup ghost turns')
   .option('--auto-retry-on-ghost-max-retries <n>', 'Maximum startup ghost retries per continuous run (default: config or 3)', parseInt)
   .option('--auto-retry-on-ghost-cooldown-seconds <n>', 'Seconds to wait between startup ghost retries (default: config or 5)', parseInt)
+  .option('--reconcile-operator-commits <mode>', 'Continuous reconcile posture for operator commits: manual, auto_safe_only, or disabled (default: config or manual; auto_safe_only under full-auto approval policy)')
   .option('--auto-checkpoint', 'Auto-commit accepted writable turns after acceptance')
   .option('--no-auto-checkpoint', 'Disable automatic checkpointing after accepted writable turns')
   .action(runCommand);

package/package.json

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

package/src/commands/reconcile-state.js

@@ -0,0 +1,49 @@
+import chalk from 'chalk';
+import { loadProjectContext } from '../lib/config.js';
+import { reconcileOperatorHead } from '../lib/operator-commit-reconcile.js';
+
+export async function reconcileStateCommand(opts = {}) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = context;
+  if (config.protocol_mode !== 'governed') {
+    console.log(chalk.red('The reconcile-state command is only available for governed projects.'));
+    process.exit(1);
+  }
+
+  if (!opts.acceptOperatorHead) {
+    console.log(chalk.red('No reconciliation action selected.'));
+    console.log(chalk.dim('Run `agentxchain reconcile-state --accept-operator-head` to accept safe operator commits on top of the last checkpoint.'));
+    process.exit(1);
+  }
+
+  const result = reconcileOperatorHead(root);
+  if (!result.ok) {
+    console.log(chalk.red(`Reconcile refused (${result.error_class || 'unknown'}).`));
+    console.log(chalk.red(result.error || 'Unable to reconcile operator commits.'));
+    if (result.offending_path) {
+      console.log(chalk.dim(`Offending path: ${result.offending_path}`));
+    }
+    if (result.offending_commit) {
+      console.log(chalk.dim(`Offending commit: ${result.offending_commit}`));
+    }
+    console.log(chalk.dim('Manual recovery: inspect the commit range, restore governed state artifacts if needed, then restart from an explicit checkpoint.'));
+    process.exit(1);
+  }
+
+  if (result.no_op) {
+    console.log(chalk.green(`State already reconciled at ${result.accepted_head.slice(0, 8)}.`));
+    return;
+  }
+
+  console.log(chalk.green(`Reconciled ${result.accepted_commits.length} operator commit(s).`));
+  console.log(chalk.dim(`Previous baseline: ${result.previous_baseline}`));
+  console.log(chalk.dim(`Accepted HEAD:      ${result.accepted_head}`));
+  if (result.paths_touched.length > 0) {
+    console.log(chalk.dim(`Paths touched:      ${result.paths_touched.join(', ')}`));
+  }
+}

package/src/lib/continuity-status.js

@@ -129,8 +129,15 @@ export function getContinuityStatus(root, state) {
     && checkpoint.run_id !== state.run_id
   );
 
-  const action = deriveRecommendedContinuityAction(state);
   const drift = deriveCheckpointDrift(root, checkpoint, staleCheckpoint);
+  const action = drift.drift_detected === true
+    ? {
+        recommended_command: 'agentxchain reconcile-state --accept-operator-head',
+        recommended_reason: 'operator_commit_drift',
+        recommended_detail: 'accept safe fast-forward operator commits as the new baseline',
+        restart_recommended: false,
+      }
+    : deriveRecommendedContinuityAction(state);
 
   return {
     checkpoint,

package/src/lib/continuous-run.js

@@ -33,6 +33,8 @@ import {
   buildGhostRetryExhaustionMirror,
   classifyGhostRetryDecision,
 } from './ghost-retry.js';
+import { reconcileOperatorHead } from './operator-commit-reconcile.js';
+import { getContinuityStatus } from './continuity-status.js';
 import {
   archiveStaleIntentsForRun,
   formatLegacyIntentMigrationNotice,
@@ -335,6 +337,99 @@ export function findNextQueuedIntent(root, options = {}) {
   return findNextDispatchableIntent(root, { run_id: options.run_id || null });
 }
 
+/**
+ * BUG-62 slice 2: when `run_loop.continuous.reconcile_operator_commits` is
+ * `auto_safe_only`, the continuous loop consults the session-checkpoint /
+ * governed-state baseline vs current git HEAD before dispatch. If operator
+ * commits landed on top of the baseline and the Turn 184 safety primitive
+ * accepts them, the baseline is auto-rolled forward so the next dispatch
+ * proceeds without manual `agentxchain reconcile-state` intervention. If the
+ * safety primitive refuses the commits (governed-state edits or history
+ * rewrite), the continuous loop pauses with the refusal class mirrored into
+ * `blocked_reason.recovery.detail`, preserving the manual primitive as the
+ * operator's single audited safety function per the BUG-62 spec.
+ */
+export function maybeAutoReconcileOperatorCommits(context, session, contOpts, log = console.log) {
+  const mode = contOpts.reconcileOperatorCommits || 'manual';
+  if (mode !== 'auto_safe_only') {
+    return null;
+  }
+  const { root } = context;
+  const state = loadProjectState(root, context.config);
+  const continuity = getContinuityStatus(root, state);
+  if (!continuity || continuity.drift_detected !== true) {
+    return null;
+  }
+
+  const result = reconcileOperatorHead(root, { safetyMode: 'auto_safe_only' });
+  if (result.ok) {
+    if (result.no_op) {
+      return null;
+    }
+    const acceptedCount = result.accepted_commits?.length || 0;
+    log(
+      `Operator-commit auto-reconcile accepted ${acceptedCount} commit${acceptedCount === 1 ? '' : 's'} `
+      + `(${result.previous_baseline.slice(0, 8)} -> ${result.accepted_head.slice(0, 8)}).`
+    );
+    return null;
+  }
+
+  const errorClass = result.error_class || 'reconcile_refused';
+  const detailLines = [
+    `Operator-commit auto-reconcile refused (${errorClass}).`,
+    result.error || 'Unsafe operator commits detected; manual recovery required.',
+    'Run: agentxchain reconcile-state --accept-operator-head once the unsafe changes are resolved, or revert them.',
+  ];
+  const detail = detailLines.join(' ');
+
+  if (state) {
+    const nextState = {
+      ...state,
+      status: 'blocked',
+      blocked_on: state.blocked_on || 'operator_commit_reconcile_refused',
+      blocked_reason: {
+        ...(state.blocked_reason || {}),
+        category: 'operator_commit_reconcile_refused',
+        error_class: errorClass,
+        recovery: {
+          ...((state.blocked_reason || {}).recovery || {}),
+          recovery_action: 'agentxchain reconcile-state --accept-operator-head',
+          detail,
+        },
+      },
+    };
+    safeWriteJson(join(root, '.agentxchain', 'state.json'), nextState);
+  }
+
+  emitRunEvent(root, 'operator_commit_reconcile_refused', {
+    run_id: state?.run_id || session.current_run_id || null,
+    phase: state?.phase || state?.current_phase || null,
+    status: 'blocked',
+    payload: {
+      error_class: errorClass,
+      message: result.error || null,
+      previous_baseline: result.previous_baseline || null,
+      current_head: result.current_head || null,
+      offending_commit: result.offending_commit || null,
+      offending_path: result.offending_path || null,
+      safety_mode: 'auto_safe_only',
+    },
+  });
+
+  session.status = 'paused';
+  writeContinuousSession(root, session);
+  log(detail);
+  return {
+    ok: true,
+    status: 'blocked',
+    action: 'operator_commit_reconcile_refused',
+    run_id: session.current_run_id,
+    recovery_action: 'agentxchain reconcile-state --accept-operator-head',
+    blocked_category: 'operator_commit_reconcile_refused',
+    error_class: errorClass,
+  };
+}
+
 function reconcileContinuousStartupState(context, session, contOpts, log) {
   const { root, config } = context;
   const governedState = loadProjectState(root, config);
@@ -483,10 +578,24 @@ export function resolveContinuousOptions(opts, config) {
   const configCont = config?.run_loop?.continuous || {};
   const configGhostRetry = configCont.auto_retry_on_ghost || {};
   const explicitConfigGhostEnabled = Object.prototype.hasOwnProperty.call(configGhostRetry, 'enabled');
-  const fullAutoGhostDefault = Boolean((opts.continuous ?? configCont.enabled ?? false) && isFullAutoApprovalPolicy(config));
+  const fullAuto = Boolean((opts.continuous ?? configCont.enabled ?? false) && isFullAutoApprovalPolicy(config));
+  const fullAutoGhostDefault = fullAuto;
   const resolvedGhostEnabled = opts.autoRetryOnGhost
     ?? (explicitConfigGhostEnabled ? configGhostRetry.enabled : fullAutoGhostDefault);
 
+  const validReconcileModes = new Set(['manual', 'auto_safe_only', 'disabled']);
+  const configuredReconcile = typeof configCont.reconcile_operator_commits === 'string'
+    && validReconcileModes.has(configCont.reconcile_operator_commits)
+    ? configCont.reconcile_operator_commits
+    : null;
+  const cliReconcile = typeof opts.reconcileOperatorCommits === 'string'
+    && validReconcileModes.has(opts.reconcileOperatorCommits)
+    ? opts.reconcileOperatorCommits
+    : null;
+  const reconcileOperatorCommits = cliReconcile
+    ?? configuredReconcile
+    ?? (fullAuto ? 'auto_safe_only' : 'manual');
+
   return {
     enabled: opts.continuous ?? configCont.enabled ?? false,
     continueFrom: opts.continueFrom ?? null,
@@ -507,6 +616,7 @@ export function resolveContinuousOptions(opts, config) {
         ?? configGhostRetry.cooldown_seconds
         ?? 5,
     },
+    reconcileOperatorCommits,
   };
 }
 
@@ -564,6 +674,9 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
 
   reconcileContinuousStartupState(context, session, contOpts, log);
 
+  const reconcileBlock = maybeAutoReconcileOperatorCommits(context, session, contOpts, log);
+  if (reconcileBlock) return reconcileBlock;
+
   // Paused-session guard: if session is paused (blocked run awaiting unblock),
   // check governed state before attempting to advance. Without this guard, the
   // loop would try to startIntent() on a blocked project, hit the blocked-state

package/src/lib/normalized-config.js

@@ -646,6 +646,8 @@ export function validateRunLoopConfig(runLoop) {
   return errors;
 }
 
+export const VALID_RECONCILE_OPERATOR_COMMITS = ['manual', 'auto_safe_only', 'disabled'];
+
 function validateRunLoopContinuousConfig(path, continuous, errors) {
   if (typeof continuous !== 'object' || Array.isArray(continuous)) {
     errors.push(`${path} must be an object`);
@@ -654,6 +656,19 @@ function validateRunLoopContinuousConfig(path, continuous, errors) {
   if (continuous.auto_retry_on_ghost !== undefined && continuous.auto_retry_on_ghost !== null) {
     validateAutoRetryOnGhostConfig(`${path}.auto_retry_on_ghost`, continuous.auto_retry_on_ghost, errors);
   }
+  if (
+    continuous.reconcile_operator_commits !== undefined
+    && continuous.reconcile_operator_commits !== null
+  ) {
+    if (
+      typeof continuous.reconcile_operator_commits !== 'string'
+      || !VALID_RECONCILE_OPERATOR_COMMITS.includes(continuous.reconcile_operator_commits)
+    ) {
+      errors.push(
+        `${path}.reconcile_operator_commits must be one of: ${VALID_RECONCILE_OPERATOR_COMMITS.join(', ')}`
+      );
+    }
+  }
 }
 
 function validateAutoRetryOnGhostConfig(path, value, errors) {

package/src/lib/operator-commit-reconcile.js

@@ -0,0 +1,260 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { emitRunEvent } from './run-events.js';
+import { captureBaselineRef, readSessionCheckpoint, SESSION_PATH } from './session-checkpoint.js';
+import { safeWriteJson } from './safe-write.js';
+
+const STATE_PATH = '.agentxchain/state.json';
+const CRITICAL_DELETION_PATHS = new Set([
+  '.planning/acceptance-matrix.md',
+]);
+
+function git(root, args) {
+  return execFileSync('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+function gitOk(root, args) {
+  try {
+    execFileSync('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function extractGitError(err) {
+  const stderr = typeof err?.stderr === 'string' ? err.stderr.trim() : '';
+  const stdout = typeof err?.stdout === 'string' ? err.stdout.trim() : '';
+  return stderr || stdout || err?.message || 'git command failed';
+}
+
+function readState(root) {
+  const statePath = join(root, STATE_PATH);
+  if (!existsSync(statePath)) return null;
+  try {
+    return JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function normalizeGitRef(ref) {
+  if (typeof ref !== 'string') return null;
+  const trimmed = ref.trim();
+  if (!trimmed) return null;
+  return trimmed.startsWith('git:') ? trimmed.slice(4).trim() || null : trimmed;
+}
+
+function resolvePreviousBaseline(state, session) {
+  return (
+    normalizeGitRef(session?.baseline_ref?.git_head)
+    || normalizeGitRef(state?.accepted_integration_ref)
+    || normalizeGitRef(state?.last_completed_turn?.checkpoint_sha)
+    || null
+  );
+}
+
+function parseNameStatus(raw) {
+  if (!raw.trim()) return [];
+  return raw.split('\n').filter(Boolean).map((line) => {
+    const parts = line.split('\t');
+    const status = parts[0] || '';
+    const paths = parts.slice(1).filter(Boolean);
+    return { status, paths };
+  });
+}
+
+function listCommitPaths(root, sha) {
+  const raw = git(root, ['diff-tree', '--no-commit-id', '--name-status', '-r', sha]);
+  return parseNameStatus(raw);
+}
+
+function summarizeCommit(root, sha) {
+  const subject = git(root, ['log', '-1', '--format=%s', sha]);
+  const entries = listCommitPaths(root, sha);
+  const paths = [...new Set(entries.flatMap((entry) => entry.paths))].sort();
+  return {
+    sha,
+    subject,
+    paths_touched: paths,
+    name_status: entries,
+  };
+}
+
+function classifyUnsafeCommit(commit) {
+  for (const entry of commit.name_status) {
+    for (const pathName of entry.paths) {
+      if (pathName === '.agentxchain' || pathName.startsWith('.agentxchain/')) {
+        return {
+          error_class: 'governance_state_modified',
+          message: `Commit ${commit.sha.slice(0, 8)} modifies governed state path ${pathName}; reconcile cannot auto-accept .agentxchain edits.`,
+          commit: commit.sha,
+          path: pathName,
+        };
+      }
+      if (entry.status.startsWith('D') && CRITICAL_DELETION_PATHS.has(pathName)) {
+        return {
+          error_class: 'critical_artifact_deleted',
+          message: `Commit ${commit.sha.slice(0, 8)} deletes critical governed evidence ${pathName}; restore the artifact or restart from an explicit recovery point.`,
+          commit: commit.sha,
+          path: pathName,
+        };
+      }
+    }
+  }
+  return null;
+}
+
+function writeSessionBaseline(root, state, previousBaseline, acceptedHead, acceptedCommits) {
+  const existing = readSessionCheckpoint(root) || {};
+  const checkpoint = {
+    ...existing,
+    run_id: state?.run_id || existing.run_id || null,
+    last_checkpoint_at: new Date().toISOString(),
+    checkpoint_reason: 'operator_commit_reconciled',
+    run_status: state?.status || existing.run_status || null,
+    phase: state?.phase || state?.current_phase || existing.phase || null,
+    last_phase: state?.phase || state?.current_phase || existing.last_phase || null,
+    last_completed_turn_id: state?.last_completed_turn_id || existing.last_completed_turn_id || null,
+    baseline_ref: captureBaselineRef(root),
+    operator_commit_reconciliation: {
+      previous_baseline: previousBaseline,
+      accepted_head: acceptedHead,
+      commit_count: acceptedCommits.length,
+    },
+  };
+  writeFileSync(join(root, SESSION_PATH), JSON.stringify(checkpoint, null, 2) + '\n');
+}
+
+export function reconcileOperatorHead(root, opts = {}) {
+  let currentHead;
+  try {
+    if (git(root, ['rev-parse', '--is-inside-work-tree']) !== 'true') {
+      return { ok: false, error_class: 'not_git_repo', error: 'reconcile-state requires a git repository.' };
+    }
+    currentHead = git(root, ['rev-parse', 'HEAD']);
+  } catch (err) {
+    return { ok: false, error_class: 'git_unavailable', error: `Unable to inspect git HEAD: ${extractGitError(err)}` };
+  }
+
+  const state = readState(root);
+  const session = readSessionCheckpoint(root);
+  const previousBaseline = resolvePreviousBaseline(state, session);
+  if (!previousBaseline) {
+    return {
+      ok: false,
+      error_class: 'missing_baseline',
+      error: 'No prior checkpoint baseline found in session.json, state.accepted_integration_ref, or last_completed_turn.checkpoint_sha.',
+    };
+  }
+
+  if (previousBaseline === currentHead) {
+    return {
+      ok: true,
+      no_op: true,
+      previous_baseline: previousBaseline,
+      accepted_head: currentHead,
+      accepted_commits: [],
+    };
+  }
+
+  if (!gitOk(root, ['merge-base', '--is-ancestor', previousBaseline, currentHead])) {
+    return {
+      ok: false,
+      error_class: 'history_rewrite',
+      error: `Cannot reconcile operator HEAD: baseline ${previousBaseline.slice(0, 8)} is not an ancestor of current HEAD ${currentHead.slice(0, 8)}.`,
+      previous_baseline: previousBaseline,
+      current_head: currentHead,
+    };
+  }
+
+  let shas;
+  try {
+    shas = git(root, ['rev-list', '--reverse', `${previousBaseline}..${currentHead}`])
+      .split('\n')
+      .map((value) => value.trim())
+      .filter(Boolean);
+  } catch (err) {
+    return { ok: false, error_class: 'commit_walk_failed', error: `Failed to inspect operator commits: ${extractGitError(err)}` };
+  }
+
+  const commits = shas.map((sha) => summarizeCommit(root, sha));
+  for (const commit of commits) {
+    const unsafe = classifyUnsafeCommit(commit);
+    if (unsafe) {
+      return {
+        ok: false,
+        error_class: unsafe.error_class,
+        error: unsafe.message,
+        offending_commit: unsafe.commit,
+        offending_path: unsafe.path,
+        previous_baseline: previousBaseline,
+        current_head: currentHead,
+      };
+    }
+  }
+
+  const acceptedAt = new Date().toISOString();
+  const pathsTouched = [...new Set(commits.flatMap((commit) => commit.paths_touched))].sort();
+  const nextState = state
+    ? {
+        ...state,
+        accepted_integration_ref: `git:${currentHead}`,
+        operator_commit_reconciliation: {
+          reconciled_at: acceptedAt,
+          previous_baseline: previousBaseline,
+          accepted_head: currentHead,
+          commit_count: commits.length,
+          safety_mode: opts.safetyMode || 'manual_safe_only',
+        },
+      }
+    : null;
+
+  if (nextState) {
+    safeWriteJson(join(root, STATE_PATH), nextState);
+  }
+
+  emitRunEvent(root, 'state_reconciled_operator_commits', {
+    run_id: state?.run_id || null,
+    phase: state?.phase || state?.current_phase || null,
+    status: state?.status || null,
+    payload: {
+      previous_baseline: previousBaseline,
+      accepted_head: currentHead,
+      accepted_commits: commits.map((commit) => ({
+        sha: commit.sha,
+        subject: commit.subject,
+        paths_touched: commit.paths_touched,
+      })),
+      paths_touched: pathsTouched,
+      safety_checks: {
+        baseline_is_ancestor: true,
+        rejected_state_paths: ['.agentxchain/'],
+        rejected_deletions: [...CRITICAL_DELETION_PATHS],
+      },
+    },
+  });
+
+  writeSessionBaseline(root, nextState || state, previousBaseline, currentHead, commits);
+
+  return {
+    ok: true,
+    previous_baseline: previousBaseline,
+    accepted_head: currentHead,
+    accepted_commits: commits.map((commit) => ({
+      sha: commit.sha,
+      subject: commit.subject,
+      paths_touched: commit.paths_touched,
+    })),
+    paths_touched: pathsTouched,
+  };
+}

package/src/lib/run-events.js

@@ -46,6 +46,8 @@ export const VALID_RUN_EVENTS = [
   'session_continuation',
   'auto_retried_ghost',
   'ghost_retry_exhausted',
+  'state_reconciled_operator_commits',
+  'operator_commit_reconcile_refused',
 ];
 
 /**