agentic-orchestrator 0.1.26 → 0.1.28

package/apps/control-plane/src/core/kernel.ts

@@ -8,12 +8,9 @@ import {
   atomicWriteFile,
   withFileLock,
   nowIso,
-  stableHash,
 } from './fs.js';
-import { SchemaRegistry, loadAndValidateYaml } from './schemas.js';
-import { normalizeRepoPath } from './path-rules.js';
+import { SchemaRegistry } from './schemas.js';
 import { parseFrontMatter, buildFrontMatter } from './frontmatter.js';
-import { runGit, runCommand } from './git.js';
 import { ERROR_CODES } from './error-codes.js';
 import { ok, fail, withSuggestedActions, type ToolResponse } from './response.js';
 import {
@@ -22,17 +19,9 @@ import {
   DEFAULT_ROLE_STATUS,
   GATE_RESULT,
   STATUS,
-  TOOLS,
 } from './constants.js';
-import { AopPathLayout, ensureAopRuntimeLayout } from './path-layout.js';
-import {
-  applyWorktreeSymlinks,
-  formatWorkspaceHookWarning,
-  runWorktreePostCreate,
-  type WorkspaceHookWarning,
-} from './workspace-hooks.js';
+import { AopPathLayout } from './path-layout.js';
 import type { RuntimeSessionsSnapshot } from './runtime-sessions.js';
-import { ToolRegistryLoader } from '../mcp/tool-registry-loader.js';
 import {
   ToolHandlerRegistry,
   ToolRouter,
@@ -47,7 +36,7 @@ import { ReportingService } from '../application/services/reporting-service.js';
 import { FeatureStateService } from '../application/services/feature-state-service.js';
 import { FeatureLifecycleService } from '../application/services/feature-lifecycle-service.js';
 import { PlanService } from '../application/services/plan-service.js';
-import { PatchService } from '../application/services/patch-service.js';
+import { PatchService, type PatchValidationResult } from '../application/services/patch-service.js';
 import { GateService } from '../application/services/gate-service.js';
 import { QaIndexService } from '../application/services/qa-index-service.js';
 import { MergeService } from '../application/services/merge-service.js';
@@ -62,112 +51,27 @@ import {
   type FeatureOutcome,
 } from '../application/services/performance-analytics-service.js';
 import { GateSelectionService } from '../application/services/gate-selection-service.js';
-import { loadComposedPolicy } from '../application/services/policy-loader-service.js';
-import {
-  ACTIVITY_DETECTOR_SLOT,
-  NOTIFICATION_CHANNEL_SLOT,
-  SCM_PROVIDER_SLOT,
-  globalAdapterRegistry,
-} from '../application/adapters/adapter-registry.js';
 import type { WorkerProvider } from '../providers/providers.js';
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AnyRecord = Record<string, any>;
-
-interface KernelContext {
-  actor_type?: string;
-  actor_id?: string;
-}
-
-interface KernelConfigOverrides {
-  policyPath?: string;
-  gatesPath?: string;
-  agentsPath?: string;
-  adaptersPath?: string;
-}
-
-export interface AgentsRoleConfig {
-  system_prompt_path?: string;
-}
-
-export interface AgentsRuntimeConfig {
-  default_provider?: string;
-  default_model?: string;
-  provider_config_env?: string;
-  default_agent_config?: Record<string, unknown>;
-  provider_configs?: Record<string, Record<string, unknown>>;
-  worker_provider_mode?: 'live' | 'stub' | string;
-  worker_response_timeout_ms?: number;
-  max_consecutive_no_progress_iterations?: number;
-}
-
-export interface AgentsConfigSnapshot {
-  version?: number;
-  roles?: Record<string, AgentsRoleConfig>;
-  missing_prompt_behavior?: 'ignore' | 'error' | string;
-  runtime?: AgentsRuntimeConfig;
-}
-
-function asArray<T = unknown>(value: unknown): T[] {
-  return Array.isArray(value) ? (value as T[]) : [];
-}
-
-function readStringField(record: AnyRecord, key: string): string | null {
-  const value = record[key];
-  return typeof value === 'string' ? value : null;
-}
-
-function readNumberField(record: AnyRecord, key: string): number | null {
-  const value = record[key];
-  return typeof value === 'number' && Number.isFinite(value) ? value : null;
-}
-
-function readPositiveIntegerField(record: AnyRecord, key: string): number | null {
-  const value = record[key];
-  if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
-    return null;
-  }
-  return Math.floor(value);
-}
-
-function readBooleanField(record: AnyRecord, key: string): boolean | null {
-  const value = record[key];
-  return typeof value === 'boolean' ? value : null;
-}
-
-function readObjectField(record: AnyRecord, key: string): AnyRecord {
-  const value = record[key];
-  return value && typeof value === 'object' ? (value as AnyRecord) : {};
-}
-
-interface PolicyConfigSnapshot extends AnyRecord {
-  rbac?: Record<string, string[]>;
-}
-
-function normalizeSet(array: string[]): string[] {
-  return [...new Set(array)].sort((a, b) => a.localeCompare(b));
-}
-
-function validateAgentRuntimeTimeoutRelationships(agentsConfig: AnyRecord): void {
-  const runtime = readObjectField(agentsConfig, 'runtime');
-  if (Object.keys(runtime).length === 0) {
-    return;
-  }
-  const responseTimeoutMs = readPositiveIntegerField(runtime, 'worker_response_timeout_ms');
-  const spawnTimeoutMs = readPositiveIntegerField(runtime, 'worker_spawn_timeout_ms');
-  const idleTimeoutMs = readPositiveIntegerField(runtime, 'worker_idle_timeout_ms');
-
-  if (responseTimeoutMs != null && spawnTimeoutMs != null && spawnTimeoutMs >= responseTimeoutMs) {
-    throw new Error(
-      'invalid_agents_yaml:runtime.worker_spawn_timeout_ms must be less than runtime.worker_response_timeout_ms',
-    );
-  }
-  if (responseTimeoutMs != null && idleTimeoutMs != null && idleTimeoutMs > responseTimeoutMs) {
-    throw new Error(
-      'invalid_agents_yaml:runtime.worker_idle_timeout_ms must be less than or equal to runtime.worker_response_timeout_ms',
-    );
-  }
-}
+import type {
+  AnyRecord,
+  KernelContext,
+  KernelConfigOverrides,
+  AgentsConfigSnapshot,
+  PolicyConfigSnapshot,
+} from './kernel-types.js';
+export type { AgentsConfigSnapshot } from './kernel-types.js';
+import { readStringField } from './utils/field-readers.js';
+import {
+  emptyRuntimeSessions as utilEmptyRuntimeSessions,
+  normalizeRuntimeSessions as utilNormalizeRuntimeSessions,
+  normalizeIndexShape as utilNormalizeIndexShape,
+  isRunLeaseFresh as utilIsRunLeaseFresh,
+} from './utils/index-normalizer.js';
+import { normalizeRepoPathForState } from './utils/path-normalizers.js';
+import { ConfigurationService } from '../application/configuration-service.js';
+import { RepoOperationsService } from '../application/services/repo-operations-service.js';
+import { FeatureSendMessageService } from '../application/services/feature-send-message-service.js';
+import { registerKernelTools } from '../application/kernel-tool-wiring.js';
 
 /**
  * Deterministic orchestration kernel for multi-agent feature development.
@@ -230,6 +134,8 @@ export class AopKernel {
   private readonly costTrackingService: CostTrackingService;
   private readonly performanceAnalyticsService: PerformanceAnalyticsService;
   private readonly gateSelectionService: GateSelectionService;
+  private readonly repoOperationsService: RepoOperationsService;
+  private readonly sendMessageService: FeatureSendMessageService;
   private readonly pathLayout: AopPathLayout;
   readonly instanceId: string;
   private provider: WorkerProvider | null = null;
@@ -259,7 +165,7 @@ export class AopKernel {
     this.adaptersConfig = {};
     this.toolRegistry = null;
     this.toolHandlers = new ToolHandlerRegistry();
-    this.registerToolHandlers();
+    registerKernelTools(this.toolHandlers, this);
     this.runLeaseService = new RunLeaseService(this);
     this.collisionQueueService = new CollisionQueueService(this);
     this.lockService = new LockService(this);
@@ -275,6 +181,12 @@ export class AopKernel {
     this.costTrackingService = new CostTrackingService(this);
     this.performanceAnalyticsService = new PerformanceAnalyticsService(this);
     this.gateSelectionService = new GateSelectionService(this);
+    this.repoOperationsService = new RepoOperationsService(this);
+    this.sendMessageService = new FeatureSendMessageService({
+      readState: (id: string) => this.readState(id),
+      getRuntimeSessions: () => this.getRuntimeSessions(),
+      getProvider: () => this.provider,
+    });
     this.toolRouter = new ToolRouter(this.toolHandlers, (toolName) =>
       Promise.resolve(
         fail(ERROR_CODES.INVALID_ARGUMENT, `Unknown tool ${toolName}`, {
@@ -342,229 +254,34 @@ export class AopKernel {
   }
 
   emptyRuntimeSessions(at = nowIso()): RuntimeSessionsSnapshot {
-    return {
-      run_id: 'none',
-      orchestrator_session_id: 'unknown',
-      provider: 'unknown',
-      model: 'unknown',
-      provider_config_ref_hash: stableHash('none'),
-      owner_instance_id: 'none',
-      lease_id: 'none',
-      started_at: at,
-      last_heartbeat_at: at,
-      lease_expires_at: at,
-      orchestrator_epoch: 0,
-      feature_sessions: {},
-    };
+    return utilEmptyRuntimeSessions(at);
   }
 
   normalizeRuntimeSessions(value: unknown, at = nowIso()): RuntimeSessionsSnapshot {
-    const fallback = this.emptyRuntimeSessions(at);
-    const source = value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
-    const featureSessionsInput =
-      source.feature_sessions && typeof source.feature_sessions === 'object'
-        ? (source.feature_sessions as Record<string, unknown>)
-        : {};
-    const featureSessions: RuntimeSessionsSnapshot['feature_sessions'] = {};
-
-    for (const [featureId, raw] of Object.entries(featureSessionsInput)) {
-      if (!featureId || typeof raw !== 'object' || !raw) {
-        continue;
-      }
-      const typed = raw as Record<string, unknown>;
-      featureSessions[featureId] = {
-        planner_session_id:
-          typeof typed.planner_session_id === 'string' ? typed.planner_session_id : 'unassigned',
-        builder_session_id:
-          typeof typed.builder_session_id === 'string' ? typed.builder_session_id : 'unassigned',
-        qa_session_id: typeof typed.qa_session_id === 'string' ? typed.qa_session_id : 'unassigned',
-      };
-    }
-
-    const epoch =
-      typeof source.orchestrator_epoch === 'number' && Number.isFinite(source.orchestrator_epoch)
-        ? Math.max(0, Math.floor(source.orchestrator_epoch))
-        : 0;
-
-    return {
-      run_id: typeof source.run_id === 'string' && source.run_id ? source.run_id : fallback.run_id,
-      orchestrator_session_id:
-        typeof source.orchestrator_session_id === 'string' && source.orchestrator_session_id
-          ? source.orchestrator_session_id
-          : fallback.orchestrator_session_id,
-      provider:
-        typeof source.provider === 'string' && source.provider
-          ? source.provider
-          : fallback.provider,
-      model: typeof source.model === 'string' && source.model ? source.model : fallback.model,
-      provider_config_ref_hash:
-        typeof source.provider_config_ref_hash === 'string' && source.provider_config_ref_hash
-          ? source.provider_config_ref_hash
-          : fallback.provider_config_ref_hash,
-      owner_instance_id:
-        typeof source.owner_instance_id === 'string' && source.owner_instance_id
-          ? source.owner_instance_id
-          : fallback.owner_instance_id,
-      lease_id:
-        typeof source.lease_id === 'string' && source.lease_id
-          ? source.lease_id
-          : fallback.lease_id,
-      started_at:
-        typeof source.started_at === 'string' && source.started_at
-          ? source.started_at
-          : fallback.started_at,
-      last_heartbeat_at:
-        typeof source.last_heartbeat_at === 'string' && source.last_heartbeat_at
-          ? source.last_heartbeat_at
-          : fallback.last_heartbeat_at,
-      lease_expires_at:
-        typeof source.lease_expires_at === 'string' && source.lease_expires_at
-          ? source.lease_expires_at
-          : fallback.lease_expires_at,
-      orchestrator_epoch: epoch,
-      feature_sessions: featureSessions,
-    };
+    return utilNormalizeRuntimeSessions(value, at);
   }
 
   normalizeIndexShape(value: unknown): AnyRecord {
-    const now = nowIso();
-    const source = value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
-    return {
-      version:
-        typeof source.version === 'number' && Number.isFinite(source.version)
-          ? Math.max(1, Math.floor(source.version))
-          : 1,
-      active: normalizeSet(
-        asArray<string>(source.active).filter((item) => typeof item === 'string'),
-      ),
-      blocked: normalizeSet(
-        asArray<string>(source.blocked).filter((item) => typeof item === 'string'),
-      ),
-      merged: normalizeSet(
-        asArray<string>(source.merged).filter((item) => typeof item === 'string'),
-      ),
-      locks: source.locks && typeof source.locks === 'object' ? source.locks : {},
-      lock_leases:
-        source.lock_leases && typeof source.lock_leases === 'object' ? source.lock_leases : {},
-      blocked_queue: asArray(source.blocked_queue).filter(
-        (item) => item && typeof item === 'object',
-      ),
-      dep_blocked: asArray(source.dep_blocked).filter((item) => item && typeof item === 'object'),
-      updated_at:
-        typeof source.updated_at === 'string' && source.updated_at ? source.updated_at : now,
-      runtime_sessions: this.normalizeRuntimeSessions(source.runtime_sessions, now),
-    };
+    return utilNormalizeIndexShape(value);
   }
 
   isRunLeaseFresh(runtimeSessions: RuntimeSessionsSnapshot): boolean {
-    const expiry = new Date(runtimeSessions.lease_expires_at).getTime();
-    if (!Number.isFinite(expiry)) {
-      return false;
-    }
-    return expiry > Date.now();
-  }
-
-  private async resolveDefaultConfigPath(fileName: string): Promise<string> {
-    const primary = path.join(this.pathLayout.orchestratorRoot, fileName);
-    if (await pathExists(primary)) {
-      return primary;
-    }
-    const legacy = path.join(this.pathLayout.legacyOrchestratorRoot, fileName);
-    if (await pathExists(legacy)) {
-      return legacy;
-    }
-    return primary;
+    return utilIsRunLeaseFresh(runtimeSessions);
   }
 
   async load() {
-    await ensureAopRuntimeLayout(this.pathLayout);
-
-    const gatesPath =
-      this.configOverrides.gatesPath ?? (await this.resolveDefaultConfigPath('gates.yaml'));
-    const policyPath =
-      this.configOverrides.policyPath ?? (await this.resolveDefaultConfigPath('policy.yaml'));
-    const agentsPath =
-      this.configOverrides.agentsPath ?? (await this.resolveDefaultConfigPath('agents.yaml'));
-    const adaptersPath =
-      this.configOverrides.adaptersPath ?? (await this.resolveDefaultConfigPath('adapters.yaml'));
-
-    const gates = await loadAndValidateYaml(this.schemaRegistry, 'gates.schema.json', gatesPath);
-    if (!gates.validation.valid) {
-      throw new Error(`invalid_gates_yaml:${JSON.stringify(gates.validation.errors)}`);
-    }
-
-    const { mergedPolicy } = await loadComposedPolicy(
+    const configService = new ConfigurationService(
       this.repoRoot,
-      policyPath,
+      this.pathLayout,
       this.schemaRegistry,
-    );
-    const parsedPolicy = mergedPolicy as PolicyConfigSnapshot;
-    const implementation = readObjectField(parsedPolicy, 'implementation');
-    const testing = readObjectField(parsedPolicy, 'testing');
-
-    if (readStringField(implementation, 'workspace') !== 'nx') {
-      throw new Error(ERROR_CODES.INVALID_WORKSPACE_IMPLEMENTATION);
-    }
-    if (readStringField(testing, 'framework') !== 'vitest') {
-      throw new Error(ERROR_CODES.INVALID_WORKSPACE_IMPLEMENTATION);
-    }
-
-    const agentsExists = await pathExists(agentsPath);
-    let agents = { parsed: { version: 1, roles: {} }, validation: { valid: true, errors: [] } };
-    if (agentsExists) {
-      agents = await loadAndValidateYaml(this.schemaRegistry, 'agents.schema.json', agentsPath);
-      if (!agents.validation.valid) {
-        throw new Error(`invalid_agents_yaml:${JSON.stringify(agents.validation.errors)}`);
-      }
-      validateAgentRuntimeTimeoutRelationships(agents.parsed as AnyRecord);
-    }
-
-    const adaptersExists = await pathExists(adaptersPath);
-    let adapters = { parsed: {}, validation: { valid: true, errors: [] as unknown[] } };
-    if (adaptersExists) {
-      adapters = await loadAndValidateYaml(
-        this.schemaRegistry,
-        'adapters.schema.json',
-        adaptersPath,
-      );
-      if (!adapters.validation.valid) {
-        throw new Error(`invalid_adapters_yaml:${JSON.stringify(adapters.validation.errors)}`);
-      }
-      const parsedAdapters = readObjectField(adapters, 'parsed');
-      const notificationChannel = readStringField(parsedAdapters, NOTIFICATION_CHANNEL_SLOT.name);
-      if (notificationChannel) {
-        try {
-          globalAdapterRegistry.resolve(NOTIFICATION_CHANNEL_SLOT, notificationChannel, {});
-        } catch {
-          throw new Error(
-            `adapter_not_found:${NOTIFICATION_CHANNEL_SLOT.name}:${notificationChannel}`,
-          );
-        }
-      }
-      const activityDetector = readStringField(parsedAdapters, ACTIVITY_DETECTOR_SLOT.name);
-      if (activityDetector) {
-        try {
-          globalAdapterRegistry.resolve(ACTIVITY_DETECTOR_SLOT, activityDetector, {});
-        } catch {
-          throw new Error(`adapter_not_found:${ACTIVITY_DETECTOR_SLOT.name}:${activityDetector}`);
-        }
-      }
-      const scmProvider = readStringField(parsedAdapters, SCM_PROVIDER_SLOT.name);
-      if (scmProvider) {
-        try {
-          globalAdapterRegistry.resolve(SCM_PROVIDER_SLOT, scmProvider, {});
-        } catch {
-          throw new Error(`adapter_not_found:${SCM_PROVIDER_SLOT.name}:${scmProvider}`);
-        }
-      }
-    }
-
-    this.gatesConfig = gates.parsed;
-    this.policy = parsedPolicy;
-    this.agentsConfig = agents.parsed as AgentsConfigSnapshot;
-    this.adaptersConfig = readObjectField(adapters, 'parsed');
-    const registryLoader = new ToolRegistryLoader(this.repoRoot);
-    this.toolRegistry = await registryLoader.load();
+      this.configOverrides,
+    );
+    const config = await configService.loadAll();
+    this.gatesConfig = config.gatesConfig;
+    this.policy = config.policy;
+    this.agentsConfig = config.agentsConfig;
+    this.adaptersConfig = config.adaptersConfig;
+    this.toolRegistry = config.toolRegistry;
     this.loaded = true;
   }
 
@@ -684,208 +401,6 @@ export class AopKernel {
     return await this.toolRouter.route(toolName, args, context);
   }
 
-  private registerToolHandlers(): void {
-    this.toolHandlers.register(
-      TOOLS.FEATURE_DISCOVER_SPECS,
-      async () => await this.featureDiscoverSpecs(),
-    );
-    this.toolHandlers.register(
-      TOOLS.FEATURE_INIT,
-      async (args) => await this.featureInit(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.FEATURE_GET_CONTEXT,
-      async (args) => await this.featureGetContext(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.FEATURE_STATE_GET,
-      async (args) => await this.featureStateGet(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.FEATURE_STATE_PATCH,
-      async (args) =>
-        await this.featureStatePatch(
-          readStringField(args, 'feature_id'),
-          readNumberField(args, 'expected_version'),
-          args.patch,
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.FEATURE_LOG_APPEND,
-      async (args, context) =>
-        await this.featureLogAppend(
-          readStringField(args, 'feature_id'),
-          readStringField(args, 'note'),
-          context,
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.PLAN_SUBMIT,
-      async (args) =>
-        await this.planSubmit(
-          readStringField(args, 'feature_id'),
-          args.plan_json,
-          readNumberField(args, 'expected_version'),
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.PLAN_GET,
-      async (args) => await this.planGet(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.PLAN_UPDATE,
-      async (args) =>
-        await this.planUpdate(
-          readStringField(args, 'feature_id'),
-          readNumberField(args, 'expected_plan_version'),
-          args.plan_json,
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.REPO_ENSURE_WORKTREE,
-      async (args) => await this.repoEnsureWorktree(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.REPO_APPLY_PATCH,
-      async (args) =>
-        await this.repoApplyPatch(
-          readStringField(args, 'feature_id'),
-          readStringField(args, 'unified_diff'),
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.REPO_STATUS,
-      async (args) => await this.repoStatus(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.REPO_DIFF,
-      async (args) =>
-        await this.repoDiff(readStringField(args, 'feature_id'), asArray<string>(args.options)),
-    );
-    this.toolHandlers.register(
-      TOOLS.REPO_READ_FILE,
-      async (args) =>
-        await this.repoReadFile(readStringField(args, 'feature_id'), readStringField(args, 'path')),
-    );
-    this.toolHandlers.register(
-      TOOLS.REPO_SEARCH,
-      async (args) =>
-        await this.repoSearch(readStringField(args, 'feature_id'), readStringField(args, 'query')),
-    );
-    this.toolHandlers.register(
-      TOOLS.REPO_DIFF_BUNDLE,
-      async (args) => await this.repoDiffBundle(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.FEATURE_READY_TO_MERGE,
-      async (args) =>
-        await this.featureReadyToMerge(
-          readStringField(args, 'feature_id'),
-          readStringField(args, 'commit_message'),
-          readStringField(args, 'merge_strategy'),
-          readStringField(args, 'user_approval_token'),
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.FEATURE_DELETE,
-      async (args) =>
-        await this.featureDelete(
-          readStringField(args, 'feature_id'),
-          readBooleanField(args, 'dry_run'),
-          readBooleanField(args, 'confirm'),
-          readBooleanField(args, 'remove_worktree'),
-          readStringField(args, 'remove_branch'),
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.GATES_LIST,
-      async (args) => await this.gatesList(readStringField(args, 'profile')),
-    );
-    this.toolHandlers.register(
-      TOOLS.GATES_RUN,
-      async (args) =>
-        await this.gatesRun(
-          readStringField(args, 'feature_id'),
-          readStringField(args, 'profile'),
-          readStringField(args, 'mode'),
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.EVIDENCE_LATEST,
-      async (args) => await this.evidenceLatest(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.QA_TEST_INDEX_GET,
-      async (args) => await this.qaTestIndexGet(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.QA_TEST_INDEX_UPDATE,
-      async (args) =>
-        await this.qaTestIndexUpdate(
-          readStringField(args, 'feature_id'),
-          readNumberField(args, 'expected_version'),
-          args.updates,
-          asArray(args.evidence_refs),
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.LOCKS_ACQUIRE,
-      async (args) =>
-        await this.locksAcquire(
-          readStringField(args, 'resource'),
-          readStringField(args, 'feature_id'),
-          readNumberField(args, 'wait_timeout_seconds'),
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.LOCKS_RELEASE,
-      async (args) =>
-        await this.locksRelease(
-          readStringField(args, 'resource'),
-          readStringField(args, 'feature_id'),
-        ),
-    );
-    this.toolHandlers.register(TOOLS.COLLISIONS_SCAN, async () => await this.collisionsScan());
-    this.toolHandlers.register(TOOLS.REPORT_DASHBOARD, async () => await this.reportDashboard());
-    this.toolHandlers.register(
-      TOOLS.REPORT_FEATURE_SUMMARY,
-      async (args) => await this.reportFeatureSummary(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.FEATURE_SEND_MESSAGE,
-      async (args) =>
-        await this.featureSendMessage(
-          readStringField(args, 'feature_id'),
-          readStringField(args, 'message'),
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.COST_RECORD,
-      async (args) =>
-        await this.costRecord(
-          readStringField(args, 'feature_id'),
-          typeof args.tokens_used_delta === 'number' ? args.tokens_used_delta : 0,
-          typeof args.estimated_cost_usd_delta === 'number' ? args.estimated_cost_usd_delta : 0,
-        ),
-    );
-    this.toolHandlers.register(
-      TOOLS.COST_GET,
-      async (args) => await this.costGet(readStringField(args, 'feature_id')),
-    );
-    this.toolHandlers.register(
-      TOOLS.PERFORMANCE_RECORD_OUTCOME,
-      async (args) => await this.performanceRecordOutcome(args),
-    );
-    this.toolHandlers.register(
-      TOOLS.PERFORMANCE_GET_ANALYTICS,
-      async (args) =>
-        await this.performanceGetAnalytics(
-          readStringField(args, 'provider'),
-          readStringField(args, 'model'),
-        ),
-    );
-  }
-
   featurePath(featureId) {
     return this.pathLayout.featureRoot(featureId);
   }
@@ -946,12 +461,15 @@ export class AopKernel {
   }
 
   makeDefaultState(featureId, branch, worktreePath) {
+    const configuredExecutionMode =
+      this.agentsConfig.runtime?.execution_mode === 'interactive' ? 'interactive' : 'deterministic';
     return {
       feature_id: featureId,
       version: 1,
       branch,
       worktree_path: normalizeRepoPathForState(this.repoRoot, worktreePath),
       status: STATUS.PLANNING,
+      execution_mode: configuredExecutionMode,
       gate_profile: 'default',
       gates: {
         plan: GATE_RESULT.NA,
@@ -969,6 +487,7 @@ export class AopKernel {
       },
       cluster: { ...DEFAULT_CLUSTER },
       role_status: { ...DEFAULT_ROLE_STATUS },
+      checkpoints: [],
       last_updated: nowIso(),
     };
   }
@@ -1256,106 +775,7 @@ export class AopKernel {
   }
 
   async repoEnsureWorktree(featureId) {
-    const worktree = this.worktreePath(featureId);
-    const branch = featureId;
-    await ensureDir(path.join(this.repoRoot, '.worktrees'));
-
-    if (await pathExists(worktree)) {
-      return {
-        data: {
-          feature_id: featureId,
-          branch,
-          worktree_path_abs: worktree,
-          existed: true,
-        },
-      };
-    }
-
-    const baseBranch = this.policy.worktree.base_branch;
-    const baseCheck = await runGit(this.repoRoot, ['rev-parse', '--verify', baseBranch]);
-    const baseRef = baseCheck.code === 0 ? baseBranch : 'HEAD';
-
-    const branchCheck = await runGit(this.repoRoot, ['rev-parse', '--verify', branch]);
-    if (branchCheck.code !== 0) {
-      const branchCreate = await runGit(this.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(this.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 = this.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(
-        this.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,
-      },
-    };
+    return this.repoOperationsService.repoEnsureWorktree(featureId);
   }
 
   async loadAcceptedPlan(featureId) {
@@ -1370,145 +790,28 @@ export class AopKernel {
     return await this.patchService.repoApplyPatch(featureId, unifiedDiff);
   }
 
-  async repoStatus(featureId) {
-    const worktree = this.worktreePath(featureId);
-    const status = await runGit(this.repoRoot, ['status', '--porcelain'], { cwd: worktree });
-    const branch = await runGit(this.repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD'], {
-      cwd: worktree,
-    });
+  async validatePatchDiff(featureId: string, parsedDiff: unknown): Promise<PatchValidationResult> {
+    return await this.patchService.validateDiff(featureId, parsedDiff);
+  }
 
-    return {
-      data: {
-        feature_id: featureId,
-        branch: branch.stdout.trim(),
-        status_porcelain: status.stdout.trim().split('\n').filter(Boolean),
-      },
-    };
+  async repoStatus(featureId) {
+    return this.repoOperationsService.repoStatus(featureId);
   }
 
   async repoDiff(featureId, options = []) {
-    const safeOptions = asArray<string>(options).filter(
-      (option) => typeof option === 'string' && option.startsWith('--'),
-    );
-    const diff = await runGit(this.repoRoot, ['diff', ...safeOptions], {
-      cwd: this.worktreePath(featureId),
-    });
-    return {
-      data: {
-        feature_id: featureId,
-        diff: diff.stdout,
-      },
-    };
+    return this.repoOperationsService.repoDiff(featureId, options);
   }
 
   async repoReadFile(featureId, filePath) {
-    const normalized = await normalizeRepoPath(
-      this.repoRoot,
-      path.join(this.worktreePath(featureId), filePath),
-      this.policy.path_rules.allow_symlink_traversal,
-    ).then((relative) =>
-      normalizeFromWorktree(this.worktreePath(featureId), this.repoRoot, relative),
-    );
-    const absolute = path.join(this.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,
-      },
-    };
+    return this.repoOperationsService.repoReadFile(featureId, filePath);
   }
 
   async repoSearch(featureId, query) {
-    const worktree = this.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,
-      },
-    };
+    return this.repoOperationsService.repoSearch(featureId, query);
   }
 
   async repoDiffBundle(featureId) {
-    const stat = await runGit(this.repoRoot, ['diff', '--stat'], {
-      cwd: this.worktreePath(featureId),
-    });
-    const full = await runGit(this.repoRoot, ['diff'], { cwd: this.worktreePath(featureId) });
-    const names = await runGit(this.repoRoot, ['diff', '--name-only'], {
-      cwd: this.worktreePath(featureId),
-    });
-    const latest = await this.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,
-      },
-    };
+    return this.repoOperationsService.repoDiffBundle(featureId);
   }
 
   async gatesList(profileName = null) {
@@ -1592,107 +895,8 @@ export class AopKernel {
     return await this.lockService.recoverFromState();
   }
 
-  private async waitForSessionToBecomeActive(sessionId: string): Promise<void> {
-    if (!this.provider?.getSessionInfo) {
-      return;
-    }
-
-    const timeoutMs = 5000;
-    const pollIntervalMs = 250;
-    const deadline = Date.now() + timeoutMs;
-
-    while (Date.now() <= deadline) {
-      const sessionInfo = await this.provider.getSessionInfo(sessionId).catch(() => null);
-      if (sessionInfo?.active) {
-        return;
-      }
-      await new Promise<void>((resolve) => {
-        setTimeout(resolve, pollIntervalMs);
-      });
-    }
-  }
-
   async featureSendMessage(featureId: string | null, message: string | null): Promise<unknown> {
-    if (!featureId) {
-      throw {
-        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'feature_id is required', {
-          retryable: false,
-          requires_human: false,
-        }),
-      };
-    }
-    if (!message) {
-      throw {
-        normalizedResponse: fail(
-          ERROR_CODES.INVALID_ARGUMENT,
-          'message is required and must not be empty',
-          { retryable: false, requires_human: false },
-        ),
-      };
-    }
-
-    const runtimeSessions = await this.getRuntimeSessions();
-    const featureSession = runtimeSessions.feature_sessions?.[featureId];
-    if (!featureSession) {
-      throw {
-        normalizedResponse: {
-          ok: false,
-          error: { code: 'session_not_found', message: 'No active session cluster for feature' },
-        },
-      };
-    }
-
-    const state = await this.readState(featureId);
-    const status = typeof state.frontMatter.status === 'string' ? state.frontMatter.status : '';
-    const gates = readObjectField(state.frontMatter, 'gates');
-
-    let targetRole = 'orchestrator';
-    let targetSessionId = runtimeSessions.orchestrator_session_id;
-
-    if (status === STATUS.PLANNING) {
-      targetRole = 'planner';
-      targetSessionId = featureSession.planner_session_id;
-    } else if (status === STATUS.BUILDING) {
-      targetRole = 'builder';
-      targetSessionId = featureSession.builder_session_id;
-    } else if (status === STATUS.QA || status === STATUS.READY_TO_MERGE) {
-      targetRole = 'qa';
-      targetSessionId = featureSession.qa_session_id;
-    } else if (status === STATUS.BLOCKED) {
-      const fastGate = readStringField(gates, 'fast');
-      const fullGate = readStringField(gates, 'full');
-      if (fastGate === GATE_RESULT.FAIL && fullGate !== GATE_RESULT.FAIL) {
-        targetRole = 'builder';
-        targetSessionId = featureSession.builder_session_id;
-      } else {
-        targetRole = 'qa';
-        targetSessionId = featureSession.qa_session_id;
-      }
-    }
-
-    if (!targetSessionId || targetSessionId === 'unassigned' || targetSessionId === 'unknown') {
-      targetRole = 'orchestrator';
-      targetSessionId = runtimeSessions.orchestrator_session_id;
-    }
-
-    if (!this.provider?.sendMessage) {
-      throw {
-        normalizedResponse: {
-          ok: false,
-          error: { code: 'provider_unsupported', message: 'Provider does not support sendMessage' },
-        },
-      };
-    }
-
-    await this.waitForSessionToBecomeActive(targetSessionId);
-    await this.provider.sendMessage(targetSessionId, message);
-    return {
-      feature_id: featureId,
-      session_id: targetSessionId,
-      target_role: targetRole,
-      status,
-      delivered: true,
-    };
+    return this.sendMessageService.featureSendMessage(featureId, message);
   }
 
   async costRecord(featureId: string, tokensDelta: number, costUsdDelta: number) {
@@ -1745,24 +949,3 @@ export class AopKernel {
     return { ok: true as const, data: snapshot };
   }
 }
-
-function normalizeRepoPathForState(repoRoot: string, absolutePath: string) {
-  const relative = path.relative(repoRoot, absolutePath).replaceAll('\\\\', '/');
-  if (!relative || relative === '.') {
-    return '.';
-  }
-  return relative;
-}
-
-function normalizeFromWorktree(
-  worktreePath: string,
-  repoRoot: string,
-  repoRelativeFromWorktree: string,
-) {
-  const absolute = path.resolve(repoRoot, repoRelativeFromWorktree);
-  const maybeRelativeToWorktree = path.relative(worktreePath, absolute).replaceAll('\\\\', '/');
-  if (!maybeRelativeToWorktree.startsWith('../')) {
-    return maybeRelativeToWorktree;
-  }
-  return path.relative(repoRoot, absolute).replaceAll('\\\\', '/');
-}