agentic-orchestrator 0.1.0

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

@@ -0,0 +1,1077 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ensureDir, pathExists, readJson, atomicWriteJson, atomicWriteFile, withFileLock, nowIso, stableHash } from './fs.js';
+import { SchemaRegistry, loadAndValidateYaml } from './schemas.js';
+import { normalizeRepoPath } from './path-rules.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 { ALLOWED_ACTORS, DEFAULT_CLUSTER, DEFAULT_ROLE_STATUS, GATE_RESULT, STATUS, TOOLS } from './constants.js';
+import { AopPathLayout, ensureAopRuntimeLayout } from './path-layout.js';
+import type { RuntimeSessionsSnapshot } from './runtime-sessions.js';
+import { ToolRegistryLoader } from '../mcp/tool-registry-loader.js';
+import { ToolHandlerRegistry, ToolRouter, type ToolHandlerContext } from '../application/tools/tool-router.js';
+import { RunLeaseService, type AcquireRunLeaseInput } from '../application/services/run-lease-service.js';
+import { LockService } from '../application/services/lock-service.js';
+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 { GateService } from '../application/services/gate-service.js';
+import { QaIndexService } from '../application/services/qa-index-service.js';
+import { MergeService } from '../application/services/merge-service.js';
+import { CollisionQueueService } from '../application/services/collision-queue-service.js';
+import { FeatureDeletionService, type FeatureDeleteResult } from '../application/services/feature-deletion-service.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+interface KernelContext {
+  actor_type?: string;
+  actor_id?: string;
+}
+
+export interface AgentsRoleConfig {
+  system_prompt_path?: string;
+}
+
+export interface AgentsRuntimeConfig {
+  default_provider?: string;
+  default_model?: string;
+  provider_config_env?: string;
+}
+
+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 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));
+}
+
+export class AopKernel {
+  repoRoot: string;
+  schemaRegistry: SchemaRegistry;
+  loaded: boolean;
+  gatesConfig: AnyRecord;
+  policy: PolicyConfigSnapshot;
+  agentsConfig: AgentsConfigSnapshot;
+  toolRegistry: AnyRecord | null;
+  toolHandlers: ToolHandlerRegistry;
+  toolRouter: ToolRouter;
+  private readonly runLeaseService: RunLeaseService;
+  private readonly lockService: LockService;
+  readonly collisionQueueService: CollisionQueueService;
+  private readonly reportingService: ReportingService;
+  private readonly featureStateService: FeatureStateService;
+  private readonly featureLifecycleService: FeatureLifecycleService;
+  private readonly planService: PlanService;
+  private readonly patchService: PatchService;
+  private readonly gateService: GateService;
+  private readonly qaIndexService: QaIndexService;
+  private readonly mergeService: MergeService;
+  private readonly featureDeletionService: FeatureDeletionService;
+  private readonly pathLayout: AopPathLayout;
+
+  constructor(repoRoot: string) {
+    this.repoRoot = repoRoot;
+    this.pathLayout = new AopPathLayout(repoRoot);
+    this.schemaRegistry = new SchemaRegistry(repoRoot);
+    this.loaded = false;
+    this.gatesConfig = {};
+    this.policy = {};
+    this.agentsConfig = {};
+    this.toolRegistry = null;
+    this.toolHandlers = new ToolHandlerRegistry();
+    this.registerToolHandlers();
+    this.runLeaseService = new RunLeaseService(this);
+    this.collisionQueueService = new CollisionQueueService(this);
+    this.lockService = new LockService(this);
+    this.reportingService = new ReportingService(this);
+    this.featureStateService = new FeatureStateService(this);
+    this.featureLifecycleService = new FeatureLifecycleService(this);
+    this.planService = new PlanService(this);
+    this.patchService = new PatchService(this);
+    this.gateService = new GateService(this);
+    this.qaIndexService = new QaIndexService(this);
+    this.mergeService = new MergeService(this);
+    this.featureDeletionService = new FeatureDeletionService(this);
+    this.toolRouter = new ToolRouter(this.toolHandlers, (toolName) =>
+      Promise.resolve(
+        fail(ERROR_CODES.INVALID_ARGUMENT, `Unknown tool ${toolName}`, {
+          retryable: false,
+          requires_human: true
+        })
+      )
+    );
+  }
+
+  getRepoRoot(): string {
+    return this.repoRoot;
+  }
+
+  getAgentsConfig(): AgentsConfigSnapshot {
+    return this.agentsConfig;
+  }
+
+  getRbacPolicy(): Record<string, string[]> {
+    return this.policy.rbac ?? {};
+  }
+
+  getPolicySnapshot(): AnyRecord {
+    return this.policy;
+  }
+
+  getGatesConfig(): AnyRecord {
+    return this.gatesConfig;
+  }
+
+  getFeaturesDir(): string {
+    return this.featuresDir;
+  }
+
+  get orchestratorDir() {
+    return this.pathLayout.orchestratorRoot;
+  }
+
+  get featuresDir() {
+    return this.pathLayout.featuresRoot;
+  }
+
+  get indexPath() {
+    return this.pathLayout.indexPath;
+  }
+
+  get indexLockPath() {
+    return this.pathLayout.indexLockPath;
+  }
+
+  runLeaseTtlSeconds() {
+    const configured = Number(this.policy?.locks?.lease_ttl_seconds ?? 300);
+    if (!Number.isFinite(configured) || configured <= 0) {
+      return 300;
+    }
+    return Math.floor(configured);
+  }
+
+  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: {}
+    };
+  }
+
+  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
+    };
+  }
+
+  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'),
+      updated_at: typeof source.updated_at === 'string' && source.updated_at ? source.updated_at : now,
+      runtime_sessions: this.normalizeRuntimeSessions(source.runtime_sessions, now)
+    };
+  }
+
+  isRunLeaseFresh(runtimeSessions: RuntimeSessionsSnapshot): boolean {
+    const expiry = new Date(runtimeSessions.lease_expires_at).getTime();
+    if (!Number.isFinite(expiry)) {
+      return false;
+    }
+    return expiry > Date.now();
+  }
+
+  async load() {
+    await ensureAopRuntimeLayout(this.pathLayout);
+
+    const gatesPath = path.join(this.orchestratorDir, 'gates.yaml');
+    const policyPath = path.join(this.orchestratorDir, 'policy.yaml');
+    const agentsPath = path.join(this.orchestratorDir, 'agents.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 policy = await loadAndValidateYaml(this.schemaRegistry, 'policy.schema.json', policyPath);
+    if (!policy.validation.valid) {
+      throw new Error(`invalid_policy_yaml:${JSON.stringify(policy.validation.errors)}`);
+    }
+
+    const parsedPolicy = policy.parsed 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)}`);
+      }
+    }
+
+    this.gatesConfig = gates.parsed;
+    this.policy = parsedPolicy;
+    this.agentsConfig = agents.parsed as AgentsConfigSnapshot;
+    const registryLoader = new ToolRegistryLoader(this.repoRoot);
+    this.toolRegistry = await registryLoader.load();
+    this.loaded = true;
+  }
+
+  async ensureLoaded() {
+    if (!this.loaded) {
+      await this.load();
+    }
+  }
+
+  authorize(actorType: string, toolName: string): boolean {
+    if (!ALLOWED_ACTORS.has(actorType)) {
+      return false;
+    }
+
+    const allowedTools = this.getRbacPolicy()[actorType] ?? [];
+    if (allowedTools.includes('*')) {
+      return true;
+    }
+    return allowedTools.includes(toolName);
+  }
+
+  async invoke(toolName: string, args: AnyRecord = {}, context: KernelContext = {}): Promise<AnyRecord> {
+    await this.ensureLoaded();
+    const actorType = context.actor_type ?? 'system';
+    const actorId = context.actor_id ?? 'system';
+
+    if (!this.authorize(actorType, toolName)) {
+      return fail(
+        ERROR_CODES.FORBIDDEN_TOOL_FOR_ROLE,
+        `Tool ${toolName} is not allowed for role ${actorType}`,
+        withSuggestedActions({ actor_type: actorType, tool_name: toolName, retryable: false, requires_human: true }, ['Use orchestrator role for this operation'])
+      );
+    }
+
+    try {
+      const result = (await this.dispatchTool(toolName, args, { actorType, actorId })) as AnyRecord;
+      return ok(result.data ?? result, result.evidence);
+    } catch (error) {
+      return this.normalizeError(error);
+    }
+  }
+
+  normalizeError(error: unknown): ToolResponse {
+    if (!error) {
+      return fail(ERROR_CODES.INTERNAL_ERROR, 'Unknown error');
+    }
+
+    if (typeof error === 'object' && error !== null && 'normalizedResponse' in error) {
+      return (error as { normalizedResponse: ToolResponse }).normalizedResponse;
+    }
+
+    const message =
+      typeof error === 'object' && error !== null && 'message' in error
+        ? (error as { message?: unknown }).message
+        : undefined;
+    const text = String(message ?? error);
+
+    if (text.startsWith('path_out_of_bounds')) {
+      return fail(ERROR_CODES.PATH_OUT_OF_BOUNDS, 'Path escapes repository root', {
+        retryable: false,
+        requires_human: true
+      });
+    }
+
+    if (text.startsWith('lock_timeout:')) {
+      return fail(ERROR_CODES.LOCK_CONFLICT, 'Timed out waiting for lock', {
+        retryable: true,
+        requires_human: false
+      });
+    }
+
+    if (text.startsWith('unknown_gate_profile_or_mode:')) {
+      return fail(ERROR_CODES.UNKNOWN_GATE_PROFILE_OR_MODE, 'Unknown gate profile or mode', {
+        value: text.split(':')[1],
+        retryable: false,
+        requires_human: true
+      });
+    }
+
+    if (text.startsWith('unsupported_parser:')) {
+      return fail(ERROR_CODES.UNSUPPORTED_PARSER, 'Gate parser type is not supported', {
+        parser: text.split(':')[1],
+        retryable: false,
+        requires_human: true
+      });
+    }
+
+    if (text.includes('qa_index_version_conflict')) {
+      return fail(ERROR_CODES.QA_INDEX_VERSION_CONFLICT, 'QA index expected_version did not match current version', {
+        retryable: true,
+        requires_human: false
+      });
+    }
+
+    return fail(ERROR_CODES.INTERNAL_ERROR, text, {
+      retryable: false,
+      requires_human: true
+    });
+  }
+
+  async dispatchTool(toolName: string, args: AnyRecord, context: ToolHandlerContext): Promise<unknown> {
+    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'))
+    );
+  }
+
+  featurePath(featureId) {
+    return this.pathLayout.featureRoot(featureId);
+  }
+
+  featureLockPath(featureId) {
+    return this.pathLayout.featureLockPath(featureId);
+  }
+
+  statePath(featureId) {
+    return this.pathLayout.statePath(featureId);
+  }
+
+  planPath(featureId) {
+    return this.pathLayout.planPath(featureId);
+  }
+
+  qaIndexPath(featureId) {
+    return this.pathLayout.qaIndexPath(featureId);
+  }
+
+  decisionsPath(featureId) {
+    return this.pathLayout.decisionsPath(featureId);
+  }
+
+  logsPath(featureId) {
+    return this.pathLayout.logsPath(featureId);
+  }
+
+  evidencePath(featureId) {
+    return this.pathLayout.evidencePath(featureId);
+  }
+
+  specPath(featureId) {
+    return this.pathLayout.specPath(featureId);
+  }
+
+  worktreePath(featureId) {
+    return path.join(this.repoRoot, '.worktrees', featureId);
+  }
+
+  async ensureFeatureLayout(featureId) {
+    const base = this.featurePath(featureId);
+    await ensureDir(base);
+    await ensureDir(this.logsPath(featureId));
+    await ensureDir(this.evidencePath(featureId));
+    const decisionsPath = this.decisionsPath(featureId);
+    if (!(await pathExists(decisionsPath))) {
+      await atomicWriteFile(decisionsPath, `# Decisions for ${featureId}\n\n`);
+    }
+  }
+
+  makeDefaultState(featureId, branch, worktreePath) {
+    return {
+      feature_id: featureId,
+      version: 1,
+      branch,
+      worktree_path: normalizeRepoPathForState(this.repoRoot, worktreePath),
+      status: STATUS.PLANNING,
+      gate_profile: 'default',
+      gates: {
+        plan: GATE_RESULT.NA,
+        fast: GATE_RESULT.NA,
+        full: GATE_RESULT.NA,
+        merge: GATE_RESULT.NA
+      },
+      locks: {
+        held: []
+      },
+      collisions: {
+        files: [],
+        areas: [],
+        contracts: []
+      },
+      cluster: { ...DEFAULT_CLUSTER },
+      role_status: { ...DEFAULT_ROLE_STATUS },
+      last_updated: nowIso()
+    };
+  }
+
+  async readState(featureId: string): Promise<{ frontMatter: AnyRecord; body: string; raw: string }> {
+    const filePath = this.statePath(featureId);
+    const raw = await fs.readFile(filePath, 'utf8');
+    const parsed = parseFrontMatter(raw);
+    return {
+      frontMatter: parsed.frontMatter,
+      body: parsed.body,
+      raw
+    };
+  }
+
+  async writeState(featureId: string, frontMatter: AnyRecord, body = '') {
+    const validation = await this.schemaRegistry.validate('state.schema.json', frontMatter);
+    if (!validation.valid) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.STATE_VALIDATION_FAILED, 'state.md front matter failed schema validation', {
+          errors: validation.errors,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const markdown = buildFrontMatter(frontMatter, body);
+    await atomicWriteFile(this.statePath(featureId), markdown);
+  }
+
+  async withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T> {
+    return await withFileLock<T>(this.featureLockPath(featureId), operation, {
+      timeoutMs: 30_000
+    });
+  }
+
+  async withIndexLock<T>(operation: () => Promise<T>): Promise<T> {
+    return await withFileLock<T>(this.indexLockPath, operation, {
+      timeoutMs: 30_000
+    });
+  }
+
+  async readIndex(): Promise<AnyRecord> {
+    const existing = await readJson(this.indexPath, null);
+    const normalized = this.normalizeIndexShape(existing);
+    const changed = JSON.stringify(existing ?? null) !== JSON.stringify(normalized);
+    if (changed) {
+      await atomicWriteJson(this.indexPath, normalized);
+    }
+    return normalized;
+  }
+
+  async writeIndex(index) {
+    const normalized = this.normalizeIndexShape(index);
+    const validation = await this.schemaRegistry.validate('index.schema.json', normalized);
+    if (!validation.valid) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INDEX_VALIDATION_FAILED, 'index.json failed schema validation', {
+          errors: validation.errors,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    await atomicWriteJson(this.indexPath, normalized);
+  }
+
+  async validateSchema(schemaName: string, value: unknown): Promise<{ valid: boolean; errors?: unknown }> {
+    return await this.schemaRegistry.validate(schemaName, value);
+  }
+
+  async getRuntimeSessions(): Promise<RuntimeSessionsSnapshot> {
+    const index = await this.readIndex();
+    return this.normalizeRuntimeSessions(index.runtime_sessions);
+  }
+
+  async acquireRunLease(input: AcquireRunLeaseInput): Promise<{ data: { runtime_sessions: RuntimeSessionsSnapshot; took_over_stale: boolean; reused_existing_owner: boolean } }> {
+    return await this.runLeaseService.acquireRunLease(input);
+  }
+
+  async renewRunLease(runId: string, ownerInstanceId: string): Promise<{ data: { lease_expires_at: string } }> {
+    return await this.runLeaseService.renewRunLease(runId, ownerInstanceId);
+  }
+
+  async releaseRunLease(runId: string, ownerInstanceId: string): Promise<{ data: { released: boolean } }> {
+    return await this.runLeaseService.releaseRunLease(runId, ownerInstanceId);
+  }
+
+  async updateOrchestratorSession(params: {
+    run_id: string;
+    owner_instance_id: string;
+    orchestrator_session_id: string;
+    increment_epoch?: boolean;
+  }): Promise<{ data: { runtime_sessions: RuntimeSessionsSnapshot } }> {
+    return await this.runLeaseService.updateOrchestratorSession(params);
+  }
+
+  async updateFeatureSessionAssignment(params: {
+    run_id: string;
+    owner_instance_id: string;
+    feature_id: string;
+    planner_session_id: string;
+    builder_session_id: string;
+    qa_session_id: string;
+  }): Promise<{ data: { updated: boolean } }> {
+    return await this.runLeaseService.updateFeatureSessionAssignment(params);
+  }
+
+  async pruneFeatureSessionAssignments(params: {
+    run_id: string;
+    owner_instance_id: string;
+    active_feature_ids: string[];
+  }): Promise<{ data: { removed: string[] } }> {
+    return await this.runLeaseService.pruneFeatureSessionAssignments(params);
+  }
+
+  async updateState(
+    featureId: string,
+    expectedVersion: number | null,
+    updater: (frontMatter: AnyRecord, body: string) => Promise<{ frontMatter?: AnyRecord; body?: string }>
+  ) {
+    return await this.featureStateService.updateState(featureId, expectedVersion, updater);
+  }
+
+  async featureDiscoverSpecs() {
+    return await this.featureLifecycleService.featureDiscoverSpecs();
+  }
+
+  async featureInit(featureId) {
+    return await this.featureLifecycleService.featureInit(featureId);
+  }
+
+  async featureGetContext(featureId) {
+    return await this.featureLifecycleService.featureGetContext(featureId);
+  }
+
+  async featureStateGet(featureId) {
+    return await this.featureStateService.featureStateGet(featureId);
+  }
+
+  async featureStatePatch(featureId, expectedVersion, patch) {
+    return await this.featureStateService.featureStatePatch(featureId, expectedVersion, patch);
+  }
+
+  async featureLogAppend(featureId, note, context) {
+    return await this.featureLifecycleService.featureLogAppend(featureId, note, context);
+  }
+
+  async planGet(featureId) {
+    return await this.planService.planGet(featureId);
+  }
+
+  async collectAcceptedPlans(excludeFeatureId = null) {
+    return await this.planService.collectAcceptedPlans(excludeFeatureId);
+  }
+
+  async requiredResourcesForPlan(plan) {
+    return await this.planService.requiredResourcesForPlan(plan);
+  }
+
+  async assertPlanLocksHeld(featureId, plan) {
+    return await this.planService.assertPlanLocksHeld(featureId, plan);
+  }
+
+  validatePlanRevisionRules(existingPlan, plan, expectedPlanVersion = null) {
+    return this.planService.validatePlanRevisionRules(existingPlan, plan, expectedPlanVersion);
+  }
+
+  async validatePlanSchema(plan) {
+    return await this.planService.validatePlanSchema(plan);
+  }
+
+  async checkPlanCollision(featureId, plan) {
+    return await this.planService.checkPlanCollision(featureId, plan);
+  }
+
+  async planSubmit(featureId, plan, expectedVersion = null) {
+    return await this.planService.planSubmit(featureId, plan, expectedVersion);
+  }
+
+  async planUpdate(featureId, expectedPlanVersion, plan) {
+    return await this.planService.planUpdate(featureId, expectedPlanVersion, plan);
+  }
+
+  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
+        })
+      };
+    }
+
+    return {
+      data: {
+        feature_id: featureId,
+        branch,
+        worktree_path_abs: worktree,
+        existed: false
+      }
+    };
+  }
+
+  async loadAcceptedPlan(featureId) {
+    return await this.patchService.loadAcceptedPlan(featureId);
+  }
+
+  async validatePatchPaths(featureId, parsedDiff, plan) {
+    return await this.patchService.validatePatchPaths(featureId, parsedDiff, plan);
+  }
+
+  async repoApplyPatch(featureId, unifiedDiff) {
+    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 });
+
+    return {
+      data: {
+        feature_id: featureId,
+        branch: branch.stdout.trim(),
+        status_porcelain: status.stdout.trim().split('\n').filter(Boolean)
+      }
+    };
+  }
+
+  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
+      }
+    };
+  }
+
+  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
+      }
+    };
+  }
+
+  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
+      }
+    };
+  }
+
+  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
+      }
+    };
+  }
+
+  async gatesList(profileName = null) {
+    return await this.gateService.gatesList(profileName);
+  }
+
+  async gateProfileAndMode(profileName, mode) {
+    return await this.gateService.gateProfileAndMode(profileName, mode);
+  }
+
+  async gatesRun(featureId, profileName, mode) {
+    return await this.gateService.gatesRun(featureId, profileName, mode);
+  }
+
+  async evidenceLatest(featureId) {
+    return await this.gateService.evidenceLatest(featureId);
+  }
+
+  async qaTestIndexGet(featureId) {
+    return await this.qaIndexService.qaTestIndexGet(featureId);
+  }
+
+  async qaTestIndexUpdate(featureId, expectedVersion, updates, evidenceRefs) {
+    return await this.qaIndexService.qaTestIndexUpdate(featureId, expectedVersion, updates, evidenceRefs);
+  }
+
+  async locksAcquire(resource, featureId, waitTimeoutSeconds = null) {
+    return await this.lockService.locksAcquire(resource, featureId, waitTimeoutSeconds);
+  }
+
+  async locksRelease(resource, featureId) {
+    return await this.lockService.locksRelease(resource, featureId);
+  }
+
+  async collisionsScan() {
+    return await this.reportingService.collisionsScan();
+  }
+
+  async reportDashboard() {
+    return await this.reportingService.reportDashboard();
+  }
+
+  async reportFeatureSummary(featureId) {
+    return await this.reportingService.reportFeatureSummary(featureId);
+  }
+
+  async featureReadyToMerge(featureId, commitMessage, mergeStrategy, userApprovalToken) {
+    return await this.mergeService.featureReadyToMerge(featureId, commitMessage, mergeStrategy, userApprovalToken);
+  }
+
+  async featureDelete(
+    featureId: string | null,
+    dryRun: boolean | null,
+    confirm: boolean | null,
+    removeWorktree: boolean | null,
+    removeBranch: string | null
+  ): Promise<FeatureDeleteResult> {
+    return await this.featureDeletionService.featureDelete(featureId, {
+      dryRun: dryRun ?? undefined,
+      confirm: confirm ?? undefined,
+      removeWorktree: removeWorktree ?? undefined,
+      removeBranch: removeBranch ?? undefined
+    });
+  }
+
+  async renewLeases(featureIds) {
+    return await this.lockService.renewLeases(featureIds);
+  }
+
+  async recoverFromState() {
+    return await this.lockService.recoverFromState();
+  }
+}
+
+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('\\\\', '/');
+}