agentic-orchestrator 0.1.28 → 0.2.0

package/packages/web-dashboard/src/lib/orchestrator-tools.ts

@@ -2,6 +2,13 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getAopRoot } from '@/lib/aop-client.js';
+import {
+  submitDashboardRuntimeCommand,
+  submitDashboardRuntimeCommandAsync,
+} from '@/lib/dashboard-runtime-client.js';
+import type { AsyncCommandSubmission } from '@/lib/dashboard-runtime-client.js';
+import { readActiveRunLease } from '@/lib/runtime-files.js';
+import type { ActiveRunLease } from '@/lib/runtime-files.js';
 
 const STATUS = {
   BLOCKED: 'blocked',
@@ -13,7 +20,13 @@ const TOOLS = {
   FEATURE_STATE_PATCH: 'feature.state_patch',
   FEATURE_LOG_APPEND: 'feature.log_append',
   FEATURE_SEND_MESSAGE: 'feature.send_message',
+  FEATURE_QUESTION_LIST: 'feature.question_list',
+  FEATURE_QUESTION_ANSWER: 'feature.question_answer',
   GATES_RUN: 'gates.run',
+  PLAN_GET: 'plan.get',
+  PLAN_UPDATE: 'plan.update',
+  REPO_RECONCILE_MAINLINE: 'repo.reconcile_mainline',
+  RUNTIME_EXECUTION_REQUEST_SUBMIT: 'runtime.execution_request_submit',
 } as const;
 
 interface ToolResponse<TData = Record<string, unknown>> {
@@ -26,17 +39,75 @@ interface ToolResponse<TData = Record<string, unknown>> {
   };
 }
 
+interface LaunchEnrollmentFeature {
+  feature_id: string;
+  spec_path: string;
+}
+
 interface RetryFeatureStatePayload extends Record<string, unknown> {
   front_matter: {
     version: number;
     status?: string;
     status_reason?: string;
+    gates?: {
+      fast?: string;
+      full?: string;
+      merge?: string;
+    };
     evidence?: {
       last_gate_mode?: string;
+      last_gate_evidence_path?: string;
+    };
+    merge_repair?: {
+      attempts?: number;
+      max_attempts?: number;
+      active?: boolean;
+      requested_at?: string | null;
+      last_failed_at?: string | null;
+      last_gate_evidence_path?: string | null;
+      last_failure_summary?: string | null;
+      reviewer_message?: string | null;
+      exhausted_at?: string | null;
+    };
+  };
+}
+
+interface MergeFeatureStatePayload extends Record<string, unknown> {
+  front_matter: {
+    gates?: {
+      merge?: string;
     };
   };
 }
 
+interface MergeGateRunPayload extends Record<string, unknown> {
+  overall?: string;
+}
+
+interface MergeReconciliationPayload extends Record<string, unknown> {
+  status?: 'up_to_date' | 'merged' | 'conflict_detected';
+  merge_base?: string;
+  mainline_head?: string;
+  worktree_head?: string;
+  conflicting_files?: string[];
+  reconciler_active_feature_id?: string | null;
+  reconciler_queue_position?: number | null;
+  dispatched_to_reconciler?: boolean;
+  conflict_worktree_prepared?: boolean;
+}
+
+interface MergeRepairState {
+  attempts: number;
+  max_attempts: number;
+  active: boolean;
+  requested_at: string | null;
+  last_failed_at: string | null;
+  last_gate_evidence_path: string | null;
+  last_failure_summary: string | null;
+  reviewer_message: string | null;
+  exhausted_at: string | null;
+}
+
 interface ToolClientIdentity {
   run_id: string;
   actor_type: string;
@@ -62,9 +133,35 @@ interface KernelLike {
   getAgentsConfig?: () => unknown;
 }
 
+interface ResumeCommandHandlerLike {
+  execute(context: {
+    repoRoot: string;
+    env: NodeJS.ProcessEnv;
+    runId: string;
+    transport: 'inprocess' | 'mcp';
+    options: {
+      command: string;
+      feature_id: string;
+      takeover_stale_run: boolean;
+    };
+    kernel: unknown;
+    toolClient: ToolClient;
+  }): Promise<unknown>;
+}
+
+interface RetryCommandHandlerLike {
+  execute(options: Record<string, unknown>): Promise<unknown>;
+}
+
 interface RuntimeBridge {
-  AopKernel: new (repoRoot: string) => KernelLike;
+  AopKernel: new (repoRoot: string, instanceId?: string) => KernelLike;
   NullWorkerProvider: new (selection: unknown) => unknown;
+  ResumeCommandHandler?: new () => ResumeCommandHandlerLike;
+  RetryCommandHandler?: new (toolClient: ToolClient, runId: string) => RetryCommandHandlerLike;
+  shouldAttemptAutoResumeAfterRetry?: (payload: {
+    ok: boolean;
+    data?: Record<string, unknown>;
+  }) => { attempt: boolean; skippedReason?: string };
   resolveProviderSelection: (input: {
     cli: Record<string, string | undefined>;
     env: NodeJS.ProcessEnv;
@@ -76,16 +173,63 @@ interface RuntimeBridge {
     options: { generateToolsMarkdown: boolean },
   ) => Promise<ToolingRuntime>;
   createOperationId?: (toolName: string, featureId?: string) => string;
+  prepareSpecDrafts?: (inputs: SpecPreparationInput[]) => PreparedSpecDraft[];
+}
+
+interface SpecPreparationInput {
+  repoRoot: string;
+  sourceContent: string;
+  sourcePath?: string | null;
+  sourceLabel?: string | null;
+  explicitFeatureId?: string | null;
+}
+
+export interface PreparedSpecDraft {
+  feature_id: string;
+  source_path: string;
+  canonical_spec_path: string;
+  source_hash: string;
+  content: string;
+  write_required: boolean;
 }
 
 interface DashboardToolRuntime {
   client: ToolClient;
   createOperationId: (toolName: string, featureId?: string) => string;
+  kernel: KernelLike;
 }
 
-const runtimeCacheByRoot = new Map<string, DashboardToolRuntime>();
+const runtimeCacheByKey = new Map<string, DashboardToolRuntime>();
 let runtimeBridgePromise: Promise<RuntimeBridge> | null = null;
 
+function hasUsableRuntimeInstanceId(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value !== 'index' &&
+    value !== 'unknown' &&
+    value !== 'none'
+  );
+}
+
+export function resolveDashboardKernelInstanceId(lease: ActiveRunLease | null): string {
+  if (lease && hasUsableRuntimeInstanceId(lease.owner_instance_id)) {
+    return lease.owner_instance_id;
+  }
+  if (lease && hasUsableRuntimeInstanceId(lease.instance_id)) {
+    return lease.instance_id;
+  }
+  return 'default';
+}
+
+export function resolveDashboardMergeCommitMessage(
+  featureId: string,
+  commitMessage?: string,
+): string {
+  const normalized = typeof commitMessage === 'string' ? commitMessage.trim() : '';
+  return normalized.length > 0 ? normalized : `feat(${featureId}): merge via dashboard approval`;
+}
+
 function makeClaims(): ToolClientIdentity {
   const stamp = Date.now();
   return {
@@ -105,6 +249,12 @@ function defaultCreateOperationId(toolName: string, featureId?: string): string
   return parts.join('__');
 }
 
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value != null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
 function normalizeError(error: unknown, fallbackCode = 'internal_error'): ToolResponse {
   if (error && typeof error === 'object') {
     const maybe = error as { code?: unknown; message?: unknown; details?: unknown };
@@ -129,6 +279,56 @@ function normalizeError(error: unknown, fallbackCode = 'internal_error'): ToolRe
   };
 }
 
+function normalizeMergeRepairState(
+  frontMatter: RetryFeatureStatePayload['front_matter'],
+): MergeRepairState {
+  const raw = frontMatter.merge_repair ?? {};
+  const maxAttempts =
+    typeof raw.max_attempts === 'number' &&
+    Number.isFinite(raw.max_attempts) &&
+    raw.max_attempts > 0
+      ? Math.floor(raw.max_attempts)
+      : 5;
+  const attempts =
+    typeof raw.attempts === 'number' && Number.isFinite(raw.attempts) && raw.attempts >= 0
+      ? Math.min(Math.floor(raw.attempts), maxAttempts)
+      : 0;
+  return {
+    attempts,
+    max_attempts: maxAttempts,
+    active: raw.active === true,
+    requested_at: typeof raw.requested_at === 'string' ? raw.requested_at : null,
+    last_failed_at: typeof raw.last_failed_at === 'string' ? raw.last_failed_at : null,
+    last_gate_evidence_path:
+      typeof raw.last_gate_evidence_path === 'string' ? raw.last_gate_evidence_path : null,
+    last_failure_summary:
+      typeof raw.last_failure_summary === 'string' ? raw.last_failure_summary : null,
+    reviewer_message: typeof raw.reviewer_message === 'string' ? raw.reviewer_message : null,
+    exhausted_at: typeof raw.exhausted_at === 'string' ? raw.exhausted_at : null,
+  };
+}
+
+function isBlockedMergeGateFailure(frontMatter: RetryFeatureStatePayload['front_matter']): boolean {
+  return (
+    frontMatter.status === STATUS.BLOCKED &&
+    frontMatter.evidence?.last_gate_mode === 'merge' &&
+    frontMatter.gates?.merge === 'fail'
+  );
+}
+
+function resolveBlockedRetryStatus(mode: string): 'building' | 'qa' | 'ready_to_merge' | null {
+  if (mode === 'fast') {
+    return 'building';
+  }
+  if (mode === 'full') {
+    return 'qa';
+  }
+  if (mode === 'merge') {
+    return 'ready_to_merge';
+  }
+  return null;
+}
+
 async function loadRuntimeBridge(): Promise<RuntimeBridge> {
   if (runtimeBridgePromise) {
     return runtimeBridgePromise;
@@ -153,13 +353,16 @@ async function loadRuntimeBridge(): Promise<RuntimeBridge> {
 }
 
 async function getRuntime(repoRoot: string): Promise<DashboardToolRuntime> {
-  const cached = runtimeCacheByRoot.get(repoRoot);
+  const activeLease = await readActiveRunLease(repoRoot);
+  const instanceId = resolveDashboardKernelInstanceId(activeLease);
+  const cacheKey = `${repoRoot}::${instanceId}`;
+  const cached = runtimeCacheByKey.get(cacheKey);
   if (cached) {
     return cached;
   }
 
   const bridge = await loadRuntimeBridge();
-  const kernel = new bridge.AopKernel(repoRoot);
+  const kernel = new bridge.AopKernel(repoRoot, instanceId);
   await kernel.ensureLoaded();
 
   try {
@@ -188,8 +391,9 @@ async function getRuntime(repoRoot: string): Promise<DashboardToolRuntime> {
   const runtime = {
     client: tooling.inProcessClient,
     createOperationId: bridge.createOperationId ?? defaultCreateOperationId,
+    kernel,
   };
-  runtimeCacheByRoot.set(repoRoot, runtime);
+  runtimeCacheByKey.set(cacheKey, runtime);
   return runtime;
 }
 
@@ -214,6 +418,243 @@ export async function callOrchestratorTool<TData = Record<string, unknown>>(
   }
 }
 
+export function preparePlanAmendment(args: {
+  featureId: string;
+  currentPlan: unknown;
+  amendedPlan: unknown;
+  revisionReason: string;
+}): {
+  expectedPlanVersion: number;
+  nextPlan: Record<string, unknown>;
+} | null {
+  const currentPlan = asRecord(args.currentPlan);
+  const amendedPlan = asRecord(args.amendedPlan);
+  if (!currentPlan || !amendedPlan) {
+    return null;
+  }
+  const currentVersion = currentPlan.plan_version;
+  if (
+    typeof currentVersion !== 'number' ||
+    !Number.isFinite(currentVersion) ||
+    currentVersion < 1 ||
+    !Number.isInteger(currentVersion)
+  ) {
+    return null;
+  }
+  const revisionReason =
+    args.revisionReason.trim().length > 0 ? args.revisionReason.trim() : 'Dashboard plan amendment';
+
+  return {
+    expectedPlanVersion: currentVersion,
+    nextPlan: {
+      ...amendedPlan,
+      feature_id: args.featureId,
+      plan_version: currentVersion + 1,
+      revision_of: currentVersion,
+      revision_reason: revisionReason,
+    },
+  };
+}
+
+export async function prepareLaunchDraftSpecs(
+  inputs: SpecPreparationInput[],
+): Promise<PreparedSpecDraft[]> {
+  const bridge = await loadRuntimeBridge();
+  if (typeof bridge.prepareSpecDrafts !== 'function') {
+    throw new Error('Spec preparation bridge is unavailable from the control-plane runtime');
+  }
+  return bridge.prepareSpecDrafts(inputs);
+}
+
+export async function amendFeaturePlan(
+  featureId: string,
+  planJson: string | Record<string, unknown>,
+  revisionReason: string,
+  repoRoot?: string,
+): Promise<
+  ToolResponse<{
+    feature_id: string;
+    accepted: boolean;
+    plan_version: number;
+    plan_json: Record<string, unknown>;
+  }>
+> {
+  const amendedPlan =
+    typeof planJson === 'string'
+      ? (() => {
+          try {
+            return JSON.parse(planJson) as Record<string, unknown>;
+          } catch {
+            return null;
+          }
+        })()
+      : planJson;
+  if (!amendedPlan) {
+    return {
+      ok: false,
+      error: {
+        code: 'invalid_argument',
+        message: 'plan_json must be valid JSON',
+      },
+    };
+  }
+
+  const current = await callOrchestratorTool<{ feature_id: string; plan: unknown }>(
+    TOOLS.PLAN_GET,
+    {
+      feature_id: featureId,
+    },
+    { featureId, repoRoot },
+  );
+  if (!current.ok || !current.data) {
+    return {
+      ok: false,
+      error: current.error,
+    };
+  }
+
+  const prepared = preparePlanAmendment({
+    featureId,
+    currentPlan: current.data.plan,
+    amendedPlan,
+    revisionReason,
+  });
+  if (!prepared) {
+    return {
+      ok: false,
+      error: {
+        code: 'invalid_argument',
+        message: 'Current accepted plan is unavailable for amendment',
+      },
+    };
+  }
+
+  const update = await callOrchestratorTool<{
+    feature_id: string;
+    accepted: boolean;
+    plan_version: number;
+  }>(
+    TOOLS.PLAN_UPDATE,
+    {
+      feature_id: featureId,
+      expected_plan_version: prepared.expectedPlanVersion,
+      plan_json: prepared.nextPlan,
+    },
+    { mutating: true, featureId, repoRoot },
+  );
+  if (!update.ok || !update.data) {
+    return {
+      ok: false,
+      error: update.error,
+    };
+  }
+
+  return {
+    ok: true,
+    data: {
+      feature_id: featureId,
+      accepted: update.data.accepted,
+      plan_version: update.data.plan_version,
+      plan_json: prepared.nextPlan,
+    },
+  };
+}
+
+export async function submitFeatureEnrollment(
+  featureId: string,
+  specPath: string,
+  runId: string,
+  ownerInstanceId: string,
+  repoRoot?: string,
+): Promise<
+  ToolResponse<{
+    run_id: string;
+    request_id: string;
+    request_status: string;
+    requested_features: Array<{ feature_id: string; spec_path: string }>;
+  }>
+> {
+  return await callOrchestratorTool(
+    TOOLS.RUNTIME_EXECUTION_REQUEST_SUBMIT,
+    {
+      run_id: runId,
+      owner_instance_id: ownerInstanceId,
+      request_type: 'add_features',
+      features: [
+        {
+          feature_id: featureId,
+          spec_path: specPath,
+        },
+      ],
+    },
+    { mutating: true, featureId, repoRoot },
+  );
+}
+
+export async function submitLaunchEnrollment(
+  features: LaunchEnrollmentFeature[],
+  repoRoot?: string,
+): Promise<
+  ToolResponse<{
+    command: 'launch.submit';
+    mode?: 'active_run_enrollment' | 'runtime_start';
+    run_id?: string;
+    request_id?: string | null;
+    request_status?: string | null;
+    requested_features?: LaunchEnrollmentFeature[];
+    handoff_started?: boolean;
+    handoff_target?: string;
+    started?: boolean;
+    already_running?: boolean;
+    feature_ids?: string[];
+  }>
+> {
+  const normalized = features
+    .filter(
+      (feature): feature is LaunchEnrollmentFeature =>
+        typeof feature.feature_id === 'string' &&
+        feature.feature_id.trim().length > 0 &&
+        typeof feature.spec_path === 'string' &&
+        feature.spec_path.trim().length > 0,
+    )
+    .map((feature) => ({
+      feature_id: feature.feature_id.trim(),
+      spec_path: feature.spec_path.trim(),
+    }))
+    .sort((left, right) => left.feature_id.localeCompare(right.feature_id));
+
+  if (normalized.length === 0) {
+    return {
+      ok: false,
+      error: {
+        code: 'invalid_input',
+        message: 'At least one prepared feature is required for launch enrollment.',
+      },
+    };
+  }
+
+  return (await submitDashboardRuntimeCommand(
+    'launch.submit',
+    normalized[0].feature_id,
+    {
+      features: normalized,
+    },
+    repoRoot ?? getAopRoot(),
+  )) as ToolResponse<{
+    command: 'launch.submit';
+    mode?: 'active_run_enrollment' | 'runtime_start';
+    run_id?: string;
+    request_id?: string | null;
+    request_status?: string | null;
+    requested_features?: LaunchEnrollmentFeature[];
+    handoff_started?: boolean;
+    handoff_target?: string;
+    started?: boolean;
+    already_running?: boolean;
+    feature_ids?: string[];
+  }>;
+}
+
 export async function approveFeatureReview(
   featureId: string,
   approvalToken: string,
@@ -221,16 +662,176 @@ export async function approveFeatureReview(
   commitMessage?: string,
   repoRoot?: string,
 ): Promise<ToolResponse> {
-  return await callOrchestratorTool(
-    TOOLS.FEATURE_READY_TO_MERGE,
+  const resolvedCommitMessage = resolveDashboardMergeCommitMessage(featureId, commitMessage);
+  return await submitDashboardRuntimeCommand(
+    'review.approve',
+    featureId,
     {
-      feature_id: featureId,
-      commit_message: commitMessage ?? `feat(${featureId}): merge via dashboard approval`,
+      approval_token: approvalToken,
+      merge_strategy: mergeStrategy,
+      commit_message: resolvedCommitMessage,
+    },
+    repoRoot ?? getAopRoot(),
+  );
+}
+
+export async function approveFeatureReviewAsync(
+  featureId: string,
+  approvalToken: string,
+  mergeStrategy = 'merge_commit',
+  commitMessage?: string,
+  repoRoot?: string,
+): Promise<AsyncCommandSubmission | ToolResponse> {
+  const resolvedCommitMessage = resolveDashboardMergeCommitMessage(featureId, commitMessage);
+  return await submitDashboardRuntimeCommandAsync(
+    'review.approve',
+    featureId,
+    {
+      approval_token: approvalToken,
       merge_strategy: mergeStrategy,
-      user_approval_token: approvalToken,
+      commit_message: resolvedCommitMessage,
+    },
+    repoRoot ?? getAopRoot(),
+  );
+}
+
+export async function runFeatureMergeGateAsync(
+  featureId: string,
+  repoRoot?: string,
+): Promise<AsyncCommandSubmission | ToolResponse> {
+  return await submitDashboardRuntimeCommandAsync(
+    'review.run_merge_gate',
+    featureId,
+    { force: true },
+    repoRoot ?? getAopRoot(),
+  );
+}
+
+export async function runFeatureMergeGate(
+  featureId: string,
+  repoRoot?: string,
+  options: { force?: boolean; commitMessage?: string } = {},
+): Promise<
+  ToolResponse<{
+    feature_id: string;
+    merge_gate_run: boolean;
+    merge_gate_overall: string | null;
+    reconciliation_status: string | null;
+  }>
+> {
+  const state = await callOrchestratorTool<MergeFeatureStatePayload>(
+    TOOLS.FEATURE_STATE_GET,
+    { feature_id: featureId },
+    { featureId, repoRoot },
+  );
+  if (!state.ok || !state.data) {
+    return {
+      ok: false,
+      error: state.error,
+    };
+  }
+
+  const mergeGatePassed = state.data.front_matter.gates?.merge === 'pass';
+  const resolvedCommitMessage = resolveDashboardMergeCommitMessage(
+    featureId,
+    options.commitMessage,
+  );
+  const reconciliation = await callOrchestratorTool<MergeReconciliationPayload>(
+    TOOLS.REPO_RECONCILE_MAINLINE,
+    {
+      feature_id: featureId,
+      auto_merge_non_conflicting: true,
+      commit_message: resolvedCommitMessage,
     },
     { mutating: true, featureId, repoRoot },
   );
+  if (!reconciliation.ok || !reconciliation.data) {
+    return {
+      ok: false,
+      error: reconciliation.error,
+    } satisfies ToolResponse<{
+      feature_id: string;
+      merge_gate_run: boolean;
+      merge_gate_overall: string | null;
+      reconciliation_status: string | null;
+    }>;
+  }
+
+  if (reconciliation.data.status === 'conflict_detected') {
+    return {
+      ok: false,
+      error: {
+        code: 'reconciliation_failed',
+        message: 'Merge requires reconciler intervention before it can continue',
+        details: {
+          feature_id: featureId,
+          merge_base: reconciliation.data.merge_base ?? null,
+          mainline_head: reconciliation.data.mainline_head ?? null,
+          worktree_head: reconciliation.data.worktree_head ?? null,
+          conflicting_files: reconciliation.data.conflicting_files ?? [],
+          reconciler_active_feature_id: reconciliation.data.reconciler_active_feature_id ?? null,
+          reconciler_queue_position: reconciliation.data.reconciler_queue_position ?? null,
+          dispatched_to_reconciler: reconciliation.data.dispatched_to_reconciler ?? false,
+          conflict_worktree_prepared: reconciliation.data.conflict_worktree_prepared ?? false,
+          retryable: false,
+          requires_human: true,
+        },
+      },
+    };
+  }
+
+  const mustRunMergeGate =
+    options.force === true || !mergeGatePassed || reconciliation.data.status === 'merged';
+  let gateOverall: string | null = mergeGatePassed ? 'pass' : null;
+  if (mustRunMergeGate) {
+    const gate = await callOrchestratorTool<MergeGateRunPayload>(
+      TOOLS.GATES_RUN,
+      {
+        feature_id: featureId,
+        mode: 'merge',
+      },
+      { mutating: true, featureId, repoRoot },
+    );
+    if (!gate.ok || !gate.data) {
+      return {
+        ok: false,
+        error: gate.error,
+      } satisfies ToolResponse<{
+        feature_id: string;
+        merge_gate_run: boolean;
+        merge_gate_overall: string | null;
+        reconciliation_status: string | null;
+      }>;
+    }
+    gateOverall = typeof gate.data.overall === 'string' ? gate.data.overall : null;
+    if (gateOverall !== 'pass') {
+      return {
+        ok: false,
+        error: {
+          code: 'merge_disabled',
+          message: 'Merge gate did not pass — merge aborted',
+          details: {
+            feature_id: featureId,
+            gate_overall: gateOverall,
+            reconciliation_status: reconciliation.data.status ?? null,
+            reconciliation_attempted: true,
+            retryable: true,
+            requires_human: false,
+          },
+        },
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    data: {
+      feature_id: featureId,
+      merge_gate_run: mustRunMergeGate,
+      merge_gate_overall: gateOverall,
+      reconciliation_status: reconciliation.data.status ?? null,
+    },
+  };
 }
 
 export async function denyFeatureReview(
@@ -283,6 +884,40 @@ export async function denyFeatureReview(
   return patchResult;
 }
 
+export async function listFeatureQuestions(
+  featureId: string,
+  status: 'open' | 'answered' | 'expired' | 'withdrawn' | 'all' = 'open',
+  repoRoot?: string,
+): Promise<ToolResponse<{ items: Array<Record<string, unknown>> }>> {
+  return await callOrchestratorTool<{ items: Array<Record<string, unknown>> }>(
+    TOOLS.FEATURE_QUESTION_LIST,
+    {
+      feature_id: featureId,
+      status,
+    },
+    { featureId, repoRoot },
+  );
+}
+
+export async function answerFeatureQuestion(
+  featureId: string,
+  questionId: string,
+  answer: string | Record<string, unknown>,
+  answeredBy: string,
+  repoRoot?: string,
+): Promise<ToolResponse> {
+  return await callOrchestratorTool(
+    TOOLS.FEATURE_QUESTION_ANSWER,
+    {
+      feature_id: featureId,
+      question_id: questionId,
+      answer,
+      answered_by: answeredBy,
+    },
+    { mutating: true, featureId, repoRoot },
+  );
+}
+
 export async function requestFeatureChanges(
   featureId: string,
   message: string,
@@ -290,6 +925,128 @@ export async function requestFeatureChanges(
 ): Promise<ToolResponse> {
   const normalized =
     message.trim().length > 0 ? message.trim() : 'Please address reviewer feedback and re-run QA.';
+  const state = await callOrchestratorTool<RetryFeatureStatePayload>(
+    TOOLS.FEATURE_STATE_GET,
+    { feature_id: featureId },
+    { featureId, repoRoot },
+  );
+  if (!state.ok || !state.data) {
+    return state as ToolResponse;
+  }
+
+  const frontMatter = state.data.front_matter;
+  if (isBlockedMergeGateFailure(frontMatter)) {
+    const mergeRepair = normalizeMergeRepairState(frontMatter);
+    if (mergeRepair.attempts >= mergeRepair.max_attempts) {
+      return {
+        ok: false,
+        error: {
+          code: 'merge_repair_exhausted',
+          message: 'Merge repair budget is exhausted for this feature',
+          details: {
+            feature_id: featureId,
+            attempts: mergeRepair.attempts,
+            max_attempts: mergeRepair.max_attempts,
+          },
+        },
+      };
+    }
+
+    const nextAttempt = mergeRepair.attempts + 1;
+    const updatedMergeRepair: MergeRepairState = {
+      ...mergeRepair,
+      attempts: nextAttempt,
+      active: true,
+      requested_at: new Date().toISOString(),
+      reviewer_message: normalized,
+      exhausted_at: null,
+    };
+    const patch = await callOrchestratorTool(
+      TOOLS.FEATURE_STATE_PATCH,
+      {
+        feature_id: featureId,
+        expected_version: frontMatter.version,
+        patch: {
+          front_matter: {
+            status: 'qa',
+            status_reason: `merge_gate_repair:${nextAttempt}`,
+            gate_retry_count: 0,
+            last_retry_at: null,
+            merge_repair: updatedMergeRepair,
+          },
+        },
+      },
+      { mutating: true, featureId, repoRoot },
+    );
+    if (!patch.ok) {
+      return patch;
+    }
+
+    const failureContext = [
+      `Reviewer requested merge-gate repair (attempt ${nextAttempt}/${updatedMergeRepair.max_attempts}).`,
+      normalized,
+      updatedMergeRepair.last_failure_summary
+        ? `Failure summary: ${updatedMergeRepair.last_failure_summary}`
+        : null,
+      updatedMergeRepair.last_gate_evidence_path
+        ? `Merge gate evidence: ${updatedMergeRepair.last_gate_evidence_path}`
+        : null,
+    ]
+      .filter((entry): entry is string => typeof entry === 'string' && entry.length > 0)
+      .join('\n');
+
+    const send = await callOrchestratorTool(
+      TOOLS.FEATURE_SEND_MESSAGE,
+      {
+        feature_id: featureId,
+        message: failureContext,
+      },
+      { mutating: true, featureId, repoRoot },
+    );
+    if (send.ok) {
+      return {
+        ok: true,
+        data: {
+          feature_id: featureId,
+          rerouted_to_qa: true,
+          merge_repair_attempt: nextAttempt,
+          merge_repair_max_attempts: updatedMergeRepair.max_attempts,
+        },
+      };
+    }
+
+    const fallback = await callOrchestratorTool(
+      TOOLS.FEATURE_LOG_APPEND,
+      {
+        feature_id: featureId,
+        note: JSON.stringify({
+          type: 'dashboard_review',
+          decision: 'request_changes',
+          merge_repair_reroute: true,
+          merge_repair_attempt: nextAttempt,
+          merge_repair_max_attempts: updatedMergeRepair.max_attempts,
+          message: normalized,
+          failure_summary: updatedMergeRepair.last_failure_summary,
+          evidence_path: updatedMergeRepair.last_gate_evidence_path,
+          reviewed_at: new Date().toISOString(),
+        }),
+      },
+      { mutating: true, featureId, repoRoot },
+    );
+    if (!fallback.ok) {
+      return fallback;
+    }
+    return {
+      ok: true,
+      data: {
+        feature_id: featureId,
+        rerouted_to_qa: true,
+        merge_repair_attempt: nextAttempt,
+        merge_repair_max_attempts: updatedMergeRepair.max_attempts,
+      },
+    };
+  }
+
   const send = await callOrchestratorTool(
     TOOLS.FEATURE_SEND_MESSAGE,
     {
@@ -334,59 +1091,88 @@ export async function sendFeatureMessage(
   );
 }
 
-export async function retryFeature(featureId: string, repoRoot?: string): Promise<ToolResponse> {
-  const state = await callOrchestratorTool<RetryFeatureStatePayload>(
-    TOOLS.FEATURE_STATE_GET,
-    { feature_id: featureId },
-    { repoRoot },
+export async function resumeFeatureExecution(
+  featureId: string,
+  repoRoot?: string,
+): Promise<ToolResponse> {
+  return await submitDashboardRuntimeCommand(
+    'feature.resume',
+    featureId,
+    {
+      takeover_stale_run: true,
+    },
+    repoRoot ?? getAopRoot(),
   );
-  if (!state.ok || !state.data) {
-    return state as ToolResponse;
-  }
+}
 
-  const status = state.data.front_matter.status ?? '';
-  const lastGateMode = state.data.front_matter.evidence?.last_gate_mode;
-  const inferredMode =
-    typeof lastGateMode === 'string' && lastGateMode.length > 0
-      ? lastGateMode
-      : status === 'building'
-        ? 'fast'
-        : status === 'qa' || status === 'ready_to_merge'
-          ? 'full'
-          : status === 'blocked' &&
-              state.data.front_matter.status_reason?.includes('forced_retry:fast')
-            ? 'fast'
-            : 'full';
-
-  if (status === 'blocked') {
-    const expectedVersion = state.data.front_matter.version;
-    const patchResult = await callOrchestratorTool(
-      TOOLS.FEATURE_STATE_PATCH,
-      {
-        feature_id: featureId,
-        expected_version: expectedVersion,
-        patch: {
-          front_matter: {
-            status: inferredMode === 'fast' ? 'building' : 'qa',
-            status_reason: `dashboard_retry:${inferredMode}`,
-            gate_retry_count: 0,
-            last_retry_at: null,
-          },
+export async function retryFeature(featureId: string, repoRoot?: string): Promise<ToolResponse> {
+  try {
+    const resolvedRoot = repoRoot ?? getAopRoot();
+    const bridge = await loadRuntimeBridge();
+    if (!bridge.RetryCommandHandler) {
+      return {
+        ok: false,
+        error: {
+          code: 'runtime_unavailable',
+          message: 'RetryCommandHandler is not available from the control-plane runtime bridge',
         },
-      },
-      { mutating: true, featureId, repoRoot },
-    );
-    if (!patchResult.ok) {
-      return patchResult;
+      };
     }
-  }
 
-  return await callOrchestratorTool(
-    TOOLS.GATES_RUN,
-    {
+    const runtime = await getRuntime(resolvedRoot);
+    const runId = `run:dashboard-retry:${Date.now()}`;
+    const handler = new bridge.RetryCommandHandler(runtime.client, runId);
+    const result = (await handler.execute({
+      command: 'retry',
       feature_id: featureId,
-      mode: inferredMode,
-    },
-    { mutating: true, featureId, repoRoot },
-  );
+      no_resume: true,
+    })) as ToolResponse;
+
+    return result;
+  } catch (error) {
+    return normalizeError(error, 'retry_failed');
+  }
+}
+
+export async function approveCollisionOverride(
+  featureId: string,
+  withFeatureId: string,
+  reason: string,
+  resume: boolean,
+  repoRoot?: string,
+): Promise<ToolResponse> {
+  try {
+    const resolvedRoot = repoRoot ?? getAopRoot();
+    const runtime = await getRuntime(resolvedRoot);
+    const kernel = runtime.kernel as unknown as Record<string, unknown>;
+    if (typeof kernel.collisionOverrideAllow !== 'function') {
+      return {
+        ok: false,
+        error: {
+          code: 'kernel_method_unavailable',
+          message: 'collisionOverrideAllow is not available on this kernel version',
+        },
+      };
+    }
+    const result = await (
+      kernel.collisionOverrideAllow as (
+        featureId: string,
+        withFeatureId: string,
+        reason: string,
+        resume: boolean,
+        createdBy: string,
+      ) => Promise<Record<string, unknown>>
+    )(featureId, withFeatureId, reason, resume, 'dashboard');
+    return { ok: true, data: result } as ToolResponse;
+  } catch (error) {
+    // Kernel throws { normalizedResponse: { ok, error } } — unwrap it.
+    const wrapped =
+      error && typeof error === 'object' && 'normalizedResponse' in error
+        ? (error as { normalizedResponse: ToolResponse }).normalizedResponse
+        : null;
+    if (wrapped && !wrapped.ok) {
+      return wrapped;
+    }
+    return normalizeError(error, 'collision_override_failed');
+  }
 }