agentic-orchestrator 0.1.26 → 0.1.28

package/apps/control-plane/src/application/services/repo-operations-service.ts

@@ -0,0 +1,276 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { pathExists, ensureDir } from '../../core/fs.js';
+import { runGit, runCommand } from '../../core/git.js';
+import { normalizeRepoPath } from '../../core/path-rules.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { fail } from '../../core/response.js';
+import {
+  applyWorktreeSymlinks,
+  formatWorkspaceHookWarning,
+  runWorktreePostCreate,
+  type WorkspaceHookWarning,
+} from '../../core/workspace-hooks.js';
+import { normalizeFromWorktree } from '../../core/utils/path-normalizers.js';
+import { asArray } from '../../core/utils/field-readers.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+export interface RepoOperationsServicePort {
+  getRepoRoot(): string;
+  worktreePath(featureId: string): string;
+  getPolicySnapshot(): AnyRecord;
+  evidenceLatest(featureId: string): Promise<{ data?: { latest?: unknown } }>;
+}
+
+export class RepoOperationsService {
+  private readonly port: RepoOperationsServicePort;
+
+  constructor(port: RepoOperationsServicePort) {
+    this.port = port;
+  }
+
+  async repoEnsureWorktree(featureId: string | null) {
+    const repoRoot = this.port.getRepoRoot();
+    const worktree = this.port.worktreePath(featureId);
+    const branch = featureId;
+    await ensureDir(path.join(repoRoot, '.worktrees'));
+
+    if (await pathExists(worktree)) {
+      return {
+        data: {
+          feature_id: featureId,
+          branch,
+          worktree_path_abs: worktree,
+          existed: true,
+        },
+      };
+    }
+
+    const policy = this.port.getPolicySnapshot();
+    const baseBranch = (policy.worktree as { base_branch: string }).base_branch;
+    const baseCheck = await runGit(repoRoot, ['rev-parse', '--verify', baseBranch]);
+    const baseRef = baseCheck.code === 0 ? baseBranch : 'HEAD';
+
+    const branchCheck = await runGit(repoRoot, ['rev-parse', '--verify', branch]);
+    if (branchCheck.code !== 0) {
+      const branchCreate = await runGit(repoRoot, ['branch', branch, baseRef]);
+      if (branchCreate.code !== 0) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.GIT_FAILURE,
+            'Unable to create feature branch',
+            {
+              feature_id: featureId,
+              stderr: branchCreate.stderr,
+              retryable: false,
+              requires_human: true,
+            },
+            {
+              command: ['git', 'branch', branch, baseRef],
+              exit_code: branchCreate.code,
+            },
+          ),
+        };
+      }
+    }
+
+    const addWorktree = await runGit(repoRoot, ['worktree', 'add', worktree, branch]);
+    if (addWorktree.code !== 0) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.GIT_FAILURE,
+          'Unable to create git worktree',
+          {
+            feature_id: featureId,
+            stderr: addWorktree.stderr,
+            retryable: false,
+            requires_human: true,
+          },
+          {
+            command: ['git', 'worktree', 'add', worktree, branch],
+            exit_code: addWorktree.code,
+          },
+        ),
+      };
+    }
+
+    const worktreeConfig = policy.worktree as
+      | {
+          base_branch: string;
+          symlinks?: string[];
+          post_create?: string[];
+        }
+      | undefined;
+    const hookWarnings: WorkspaceHookWarning[] = [];
+    const collectHookWarning = (warning: WorkspaceHookWarning) => {
+      hookWarnings.push(warning);
+    };
+
+    if (worktreeConfig?.symlinks?.length) {
+      await applyWorktreeSymlinks(repoRoot, worktree, worktreeConfig.symlinks, collectHookWarning);
+    }
+
+    if (worktreeConfig?.post_create?.length) {
+      await runWorktreePostCreate(worktree, worktreeConfig.post_create, collectHookWarning);
+    }
+
+    for (const warning of hookWarnings) {
+      // Preserve non-fatal behavior while making hook failures observable.
+      console.warn(`[aop] workspace hook warning: ${formatWorkspaceHookWarning(warning)}`);
+    }
+
+    return {
+      data: {
+        feature_id: featureId,
+        branch,
+        worktree_path_abs: worktree,
+        existed: false,
+      },
+    };
+  }
+
+  async repoStatus(featureId: string | null) {
+    const repoRoot = this.port.getRepoRoot();
+    const worktree = this.port.worktreePath(featureId);
+    const status = await runGit(repoRoot, ['status', '--porcelain'], { cwd: worktree });
+    const branch = await runGit(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: worktree,
+    });
+
+    return {
+      data: {
+        feature_id: featureId,
+        branch: branch.stdout.trim(),
+        status_porcelain: status.stdout.trim().split('\n').filter(Boolean),
+      },
+    };
+  }
+
+  async repoDiff(featureId: string | null, options: string[] = []) {
+    const repoRoot = this.port.getRepoRoot();
+    const safeOptions = asArray<string>(options).filter(
+      (option) => typeof option === 'string' && option.startsWith('--'),
+    );
+    const diff = await runGit(repoRoot, ['diff', ...safeOptions], {
+      cwd: this.port.worktreePath(featureId),
+    });
+    return {
+      data: {
+        feature_id: featureId,
+        diff: diff.stdout,
+      },
+    };
+  }
+
+  async repoReadFile(featureId: string | null, filePath: string | null) {
+    const repoRoot = this.port.getRepoRoot();
+    const worktree = this.port.worktreePath(featureId);
+    const policy = this.port.getPolicySnapshot();
+    const normalized = await normalizeRepoPath(
+      repoRoot,
+      path.join(worktree, filePath),
+      (policy.path_rules as { allow_symlink_traversal?: boolean } | undefined)
+        ?.allow_symlink_traversal,
+    ).then((relative) => normalizeFromWorktree(worktree, repoRoot, relative));
+    const absolute = path.join(repoRoot, normalized);
+    const exists = await pathExists(absolute);
+    if (!exists) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.FILE_NOT_FOUND, 'File not found', {
+          path: normalized,
+          retryable: false,
+          requires_human: false,
+        }),
+      };
+    }
+    const content = await fs.readFile(absolute, 'utf8');
+    return {
+      data: {
+        feature_id: featureId,
+        path: normalized,
+        content,
+      },
+    };
+  }
+
+  async repoSearch(featureId: string | null, query: string | null) {
+    const worktree = this.port.worktreePath(featureId);
+    const rgResult = await runCommand('rg', ['-n', '--no-heading', query, '.'], {
+      cwd: worktree,
+      timeoutMs: 30_000,
+    });
+
+    if (rgResult.code === 127) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.GIT_FAILURE,
+          'ripgrep (rg) not found - required for search functionality',
+          {
+            stderr: rgResult.stderr,
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    if (rgResult.code !== 0 && rgResult.code !== 1) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.GIT_FAILURE, 'Search failed', {
+          stderr: rgResult.stderr,
+          retryable: true,
+          requires_human: false,
+        }),
+      };
+    }
+
+    const matches = rgResult.stdout
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => {
+        const firstColon = line.indexOf(':');
+        const secondColon = line.indexOf(':', firstColon + 1);
+        if (firstColon === -1 || secondColon === -1) {
+          return { raw: line };
+        }
+        return {
+          path: line.slice(0, firstColon),
+          line: Number(line.slice(firstColon + 1, secondColon)),
+          snippet: line.slice(secondColon + 1),
+        };
+      });
+
+    return {
+      data: {
+        feature_id: featureId,
+        query,
+        matches,
+      },
+    };
+  }
+
+  async repoDiffBundle(featureId: string | null) {
+    const repoRoot = this.port.getRepoRoot();
+    const worktree = this.port.worktreePath(featureId);
+    const stat = await runGit(repoRoot, ['diff', '--stat'], { cwd: worktree });
+    const full = await runGit(repoRoot, ['diff'], { cwd: worktree });
+    const names = await runGit(repoRoot, ['diff', '--name-only'], { cwd: worktree });
+    const latest = await this.port.evidenceLatest(featureId);
+
+    return {
+      data: {
+        feature_id: featureId,
+        diff_stat: stat.stdout,
+        diff: full.stdout,
+        touched_files: names.stdout
+          .split('\n')
+          .map((x) => x.trim())
+          .filter(Boolean),
+        last_gate_summary: latest.data?.latest ?? null,
+      },
+    };
+  }
+}

package/apps/control-plane/src/application/services/worktree-watchdog-service.ts

@@ -0,0 +1,156 @@
+import { EventEmitter } from 'node:events';
+import { runGit } from '../../core/git.js';
+
+interface WatchStartInput {
+  featureId: string;
+  repoRoot: string;
+  worktreePath: string;
+  pollIntervalMs: number;
+  maxUncommittedChanges: number;
+}
+
+interface WatcherState {
+  repoRoot: string;
+  worktreePath: string;
+  maxUncommittedChanges: number;
+  timer: NodeJS.Timeout;
+  changedFiles: Set<string>;
+  thresholdEmitted: boolean;
+  pollInFlight: boolean;
+  stopped: boolean;
+}
+
+function parseStatusPaths(statusPorcelain: string): string[] {
+  const files: string[] = [];
+  const lines = statusPorcelain
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length >= 4);
+
+  for (const line of lines) {
+    const candidate = line.slice(3).trim();
+    if (!candidate) {
+      continue;
+    }
+    const renameMarker = candidate.indexOf(' -> ');
+    const pathValue = renameMarker >= 0 ? candidate.slice(renameMarker + 4) : candidate;
+    const normalized = pathValue.replaceAll('\\\\', '/').trim();
+    if (normalized.length > 0) {
+      files.push(normalized);
+    }
+  }
+
+  return [...new Set(files)].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Polling watchdog that tracks feature-worktree changes and emits threshold events.
+ */
+export class WorktreeWatchdogService extends EventEmitter {
+  private readonly watchers = new Map<string, WatcherState>();
+
+  async startWatching(input: WatchStartInput): Promise<void> {
+    await this.stopWatching(input.featureId);
+
+    const intervalMs =
+      Number.isFinite(input.pollIntervalMs) && input.pollIntervalMs > 0
+        ? Math.floor(input.pollIntervalMs)
+        : 2_000;
+    const maxUncommittedChanges =
+      Number.isFinite(input.maxUncommittedChanges) && input.maxUncommittedChanges > 0
+        ? Math.floor(input.maxUncommittedChanges)
+        : 50;
+
+    const state: WatcherState = {
+      repoRoot: input.repoRoot,
+      worktreePath: input.worktreePath,
+      maxUncommittedChanges,
+      timer: setInterval(() => {
+        void this.pollFeature(input.featureId);
+      }, intervalMs),
+      changedFiles: new Set<string>(),
+      thresholdEmitted: false,
+      pollInFlight: false,
+      stopped: false,
+    };
+
+    state.timer.unref?.();
+    this.watchers.set(input.featureId, state);
+    await this.pollFeature(input.featureId);
+  }
+
+  stopWatching(featureId: string): Promise<void> {
+    const existing = this.watchers.get(featureId);
+    if (!existing) {
+      return Promise.resolve();
+    }
+    existing.stopped = true;
+    clearInterval(existing.timer);
+    this.watchers.delete(featureId);
+    return Promise.resolve();
+  }
+
+  async getChangedFiles(featureId: string): Promise<string[]> {
+    await this.pollFeature(featureId);
+    const state = this.watchers.get(featureId);
+    if (!state) {
+      return [];
+    }
+    return [...state.changedFiles].sort((a, b) => a.localeCompare(b));
+  }
+
+  getChangeCount(featureId: string): number {
+    const state = this.watchers.get(featureId);
+    if (!state) {
+      return 0;
+    }
+    return state.changedFiles.size;
+  }
+
+  resetChangeCount(featureId: string): void {
+    const state = this.watchers.get(featureId);
+    if (!state) {
+      return;
+    }
+    state.changedFiles.clear();
+    state.thresholdEmitted = false;
+  }
+
+  on(event: 'changeThreshold', listener: (featureId: string) => void): this {
+    return super.on(event, listener);
+  }
+
+  off(event: 'changeThreshold', listener: (featureId: string) => void): this {
+    return super.off(event, listener);
+  }
+
+  private async pollFeature(featureId: string): Promise<void> {
+    const state = this.watchers.get(featureId);
+    if (!state || state.stopped || state.pollInFlight) {
+      return;
+    }
+
+    state.pollInFlight = true;
+    try {
+      const status = await runGit(state.repoRoot, ['status', '--porcelain'], {
+        cwd: state.worktreePath,
+      });
+      if (status.code !== 0) {
+        return;
+      }
+
+      const files = parseStatusPaths(status.stdout);
+      state.changedFiles = new Set(files);
+
+      if (state.changedFiles.size >= state.maxUncommittedChanges && !state.thresholdEmitted) {
+        state.thresholdEmitted = true;
+        this.emit('changeThreshold', featureId);
+      }
+      if (state.changedFiles.size < state.maxUncommittedChanges) {
+        state.thresholdEmitted = false;
+      }
+    } finally {
+      state.pollInFlight = false;
+    }
+  }
+}

package/apps/control-plane/src/cli/cli-argument-parser.ts

@@ -55,6 +55,11 @@ export class CliArgumentParser {
         index += 1;
         continue;
       }
+      if (token === '--checkpoint') {
+        options.checkpoint = next;
+        index += 1;
+        continue;
+      }
       if (token === '--dry-run') {
         const parsed = parseOptionalBooleanToken(next);
         if (parsed === null) {
@@ -106,6 +111,13 @@ export class CliArgumentParser {
         }
         continue;
       }
+      if (token === '--execution-mode') {
+        if (next === 'deterministic' || next === 'interactive') {
+          options.execution_mode = next;
+          index += 1;
+        }
+        continue;
+      }
       if (token === '--transport') {
         options.transport = next;
         index += 1;

package/apps/control-plane/src/cli/help-command-handler.ts

@@ -31,6 +31,10 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
         flag: '--worker-provider-mode <live|stub>',
         description: 'Worker execution mode override (default: live for run/resume)',
       },
+      {
+        flag: '--execution-mode <deterministic|interactive>',
+        description: 'Execution mode override for worker decision flow (default: deterministic)',
+      },
       { flag: '--transport <inprocess|mcp>', description: 'Tool transport layer (default: mcp)' },
       { flag: '--takeover-stale-run', description: 'Take over a stale run lease' },
       { flag: '--project <name>', description: 'Select project from multi-project.yaml' },
@@ -55,6 +59,10 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
         flag: '--worker-provider-mode <live|stub>',
         description: 'Worker execution mode override (default: live)',
       },
+      {
+        flag: '--execution-mode <deterministic|interactive>',
+        description: 'Execution mode override for worker decision flow (default: deterministic)',
+      },
       { flag: '--transport <inprocess|mcp>', description: 'Tool transport layer (default: mcp)' },
     ],
   },
@@ -96,6 +104,15 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
       },
     ],
   },
+  [CliCommand.Rollback]: {
+    usage: 'aop rollback [flags]',
+    description: 'Rollback a feature worktree by applying the inverse of a checkpoint snapshot.',
+    flags: [
+      { flag: '--feature-id <id>', description: 'Feature to roll back' },
+      { flag: '--checkpoint <id>', description: 'Checkpoint id to reverse-apply' },
+      { flag: '--dry-run', description: 'Preview rollback inputs without applying git changes' },
+    ],
+  },
   [CliCommand.Init]: {
     usage: 'aop init [flags]',
     description: 'Initialise agentic orchestrator configuration in the current directory.',

package/apps/control-plane/src/cli/init-command-handler.ts

@@ -30,6 +30,7 @@ export interface InitOptions {
 }
 
 type TestFramework = 'vitest' | 'jest' | 'pytest' | 'maven' | 'gradle';
+type ExecutionMode = 'deterministic' | 'interactive';
 
 interface PromptSession {
   question(query: string): Promise<string>;
@@ -46,6 +47,7 @@ interface WizardConfig {
   maxParallelGateRuns: number;
   dashboardPort: number;
   framework: TestFramework;
+  executionMode: ExecutionMode;
   defaultProvider: string;
   defaultModel: string;
   providerConfigEnv: string | null;
@@ -423,6 +425,19 @@ missing_prompt_behavior: ignore
 runtime:
   default_provider: ${wizard.defaultProvider}
   default_model: ${wizard.defaultModel}
+  execution_mode: ${wizard.executionMode}
+  interactive:
+    watchdog_poll_interval_ms: 2000
+    checkpoint_interval_ms: 30000
+    max_uncommitted_changes: 50
+    validation_on_checkpoint: true
+    revert_on_violation: false
+    violation_severity: warning
+    shadow_workspace:
+      enabled: false
+      promotion_strategy: atomic
+      cleanup_on_failure: true
+      max_shadow_size_mb: 2048
   worker_provider_mode: live
   worker_response_timeout_ms: 600000
   worker_spawn_timeout_ms: 15000
@@ -478,6 +493,14 @@ function parseFramework(raw: string, fallback: TestFramework): TestFramework {
   return fallback;
 }
 
+function parseExecutionMode(raw: string, fallback: ExecutionMode): ExecutionMode {
+  const value = raw.trim().toLowerCase();
+  if (value === 'deterministic' || value === 'interactive') {
+    return value;
+  }
+  return fallback;
+}
+
 function parseNotificationChannels(raw: string): {
   desktop: boolean;
   slack: boolean;
@@ -643,6 +666,12 @@ async function collectWizardConfig(
       }
     }
 
+    const executionModeRaw = await askWithDefault(
+      prompt,
+      'Default execution mode (deterministic|interactive)',
+      'deterministic',
+    );
+
     return {
       baseBranch,
       defaultProvider: parseAdapterName(
@@ -651,6 +680,7 @@ async function collectWizardConfig(
         defaults.defaultProvider,
       ),
       defaultModel,
+      executionMode: parseExecutionMode(executionModeRaw, 'deterministic'),
       providerConfigEnv,
       providerCredentialBootstrapped,
       scmProvider: parseAdapterName(
@@ -711,6 +741,7 @@ export class InitCommandHandler {
           baseBranch: gitContext.defaultBranch,
           defaultProvider: DEFAULT_AGENT_PROVIDER,
           defaultModel: DEFAULT_AGENT_MODEL,
+          executionMode: 'deterministic' as const,
           providerConfigEnv: null,
           providerCredentialBootstrapped: false,
           scmProvider: DEFAULT_SCM_PROVIDER,

package/apps/control-plane/src/cli/resume-command-handler.ts

@@ -3,6 +3,7 @@ import { resolveProviderSelection } from '../providers/providers.js';
 import {
   DefaultWorkerProviderFactory,
   resolveWorkerProviderMode,
+  resolveWorkerProviderObservability,
   resolveWorkerProviderPolicy,
   resolveWorkerProviderRuntime,
   type WorkerProviderFactory,
@@ -52,6 +53,14 @@ function asStringArray(value: unknown): string[] {
   return normalized;
 }
 
+function asFeatureId(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 function toResumePhase(status: string): string {
   if (status === STATUS.BUILDING) {
     return STATUS.BUILDING;
@@ -98,9 +107,10 @@ export class ResumeCommandHandler {
   }
 
   async execute(context: ResumeCommandContext): Promise<unknown> {
-    const { env, runId, transport, options, kernel, toolClient } = context;
+    const { repoRoot, env, runId, transport, options, kernel, toolClient } = context;
     const recovery = await kernel.recoverFromState();
-    const resumePlan = await this.buildResumePlan(kernel, runId);
+    const requestedFeatureId = asFeatureId(options.feature_id);
+    const resumePlan = await this.buildResumePlan(kernel, runId, requestedFeatureId);
 
     if (resumePlan.features.length === 0) {
       return {
@@ -127,6 +137,10 @@ export class ResumeCommandHandler {
       policySnapshot.execution && typeof policySnapshot.execution === 'object'
         ? (policySnapshot.execution as Record<string, unknown>)
         : null;
+    const observabilityPolicy =
+      policySnapshot.observability && typeof policySnapshot.observability === 'object'
+        ? (policySnapshot.observability as Record<string, unknown>)
+        : null;
     const provider = this.workerProviderFactory.create({
       selection,
       mode: resolveWorkerProviderMode(
@@ -136,7 +150,9 @@ export class ResumeCommandHandler {
       ),
       context: 'resume',
       policy: resolveWorkerProviderPolicy(executionPolicy),
+      observability: resolveWorkerProviderObservability(observabilityPolicy),
       runtime: runtimeConfig,
+      repoRoot,
     });
     const supervisor = new SupervisorRuntime(kernel, provider, toolClient, {
       max_active_features: 5,
@@ -144,6 +160,7 @@ export class ResumeCommandHandler {
       run_id: resumePlan.run_id,
       owner_instance_id: resumePlan.owner_instance_id,
       takeover_stale_run: options.takeover_stale_run,
+      execution_mode: options.execution_mode,
     });
 
     const startResult = await supervisor.start(
@@ -168,7 +185,11 @@ export class ResumeCommandHandler {
     };
   }
 
-  private async buildResumePlan(kernel: AopKernel, fallbackRunId: string): Promise<ResumePlan> {
+  private async buildResumePlan(
+    kernel: AopKernel,
+    fallbackRunId: string,
+    requestedFeatureId?: string | null,
+  ): Promise<ResumePlan> {
     const index = await kernel.readIndex();
     const runtimeSessions = await kernel.getRuntimeSessions();
     const discovered = await kernel.featureDiscoverSpecs();
@@ -201,7 +222,13 @@ export class ResumeCommandHandler {
     }
 
     const resumable: ResumeFeature[] = [];
-    const sortedFeatureIds = [...sourcesByFeature.keys()].sort((a, b) => a.localeCompare(b));
+    const normalizedRequestedFeatureId = asFeatureId(requestedFeatureId);
+    if (normalizedRequestedFeatureId) {
+      this.addSource(sourcesByFeature, normalizedRequestedFeatureId, 'cli.feature_id');
+    }
+    const sortedFeatureIds = normalizedRequestedFeatureId
+      ? [normalizedRequestedFeatureId]
+      : [...sourcesByFeature.keys()].sort((a, b) => a.localeCompare(b));
     for (const featureId of sortedFeatureIds) {
       try {
         const state = await kernel.featureStateGet(featureId);