@ddtcorex/dsh-maestro-review 0.4.0 → 0.5.0

package/src/host/orchestrator.ts

@@ -30,8 +30,8 @@ import * as GovardAuditLintTool from './govard-audit-lint-tool.js'
 import * as PerfLogStatsTool from './perf-log-stats-tool.js'
 import * as ReviewToolPolicy from './tool-policy.js'
 import type { ReviewFinding, FindingSeverity } from './review-findings-tool.js'
-import type { ReviewRequest } from './events.js'
-import { loadUserConfig, type MaestroUserConfig, type ReviewModelSelection } from './config-store.js'
+import type { ReviewRequest, ReviewResult } from './events.js'
+import { loadUserConfig, type MaestroUserConfig, type ProjectMapping, type ReviewModelSelection } from './config-store.js'
 import { hasCompletedReview, lastCompletedReview, pruneHistory, recordReviewFinish, recordReviewStart } from './review-history.js'
 import { buildIncrementalBlock, fetchCompare, fetchMrDetailHeadSha } from './incremental.js'
 import { createReviewSignals } from './review-signals.js'
@@ -40,6 +40,9 @@ import { loadedReviewProfile, type ReviewSkillProfile } from './skills-tool.js'
 import type { ReviewProvider } from './providers/interface.js'
 import { gitlabProvider } from './providers/gitlab.js'
 import './events.js'
+import { gitlabAuthHeaders } from './gitlab-auth.js'
+import { reviewMarker, resolveFlow, type ReviewFlow } from './review-marker.js'
+import { cloneSourceRepo, defaultRun } from './ci-clone.js'
 
 // Provider-aware wrapper — orchestrator can run reviews via any ReviewProvider.
 // This keeps the GitLab-specific flow intact while allowing Phase C to add GitHub/Jira without modifying core logic.
@@ -132,6 +135,7 @@ export function buildReviewComment(opts: {
   durationMs?: number
   isDiffOnly?: boolean
   isDiscussion?: boolean
+  marker?: { sha: string; flow: ReviewFlow }
 }): string {
   const mrUrl = `${opts.gitlabBaseUrl.replace(/\/$/, '')}/${opts.projectPath}/-/merge_requests/${opts.mrIid}`
   const title = opts.isDiffOnly === true ? '## 🤖 Maestro Review — Diff-only' : '## 🤖 Maestro Review'
@@ -167,10 +171,11 @@ export function buildReviewComment(opts: {
     ? `\n\n<details>\n<summary>⚠️ Failed to post (${opts.failures.length})</summary>\n\n${opts.failures.map((f) => `- \`${f}\``).join('\n')}\n\n</details>`
     : ''
   const footer = `\n\n---\n\n<sub>Generated by Maestro · [View MR →](${mrUrl})</sub>`
-  return `${title}\n\n${metaLine}\n\n${scopeNote}${opts.summary}${findingsLine}${failuresBlock}${footer}`
+  const markerLine = opts.marker === undefined ? '' : `\n\n${reviewMarker(opts.marker.sha, opts.marker.flow)}`
+  return `${title}\n\n${metaLine}\n\n${scopeNote}${opts.summary}${findingsLine}${failuresBlock}${footer}${markerLine}`
 }
 
-export function buildNotStartedComment(opts: { gitlabBaseUrl: string; projectPath: string; mrIid: number }): string {
+export function buildNotStartedComment(opts: { gitlabBaseUrl: string; projectPath: string; mrIid: number; marker?: { sha: string; flow: ReviewFlow } }): string {
   const mrUrl = `${opts.gitlabBaseUrl.replace(/\/$/, '')}/${opts.projectPath}/-/merge_requests/${opts.mrIid}`
   return [
     '## 🤖 Maestro Review — Not started',
@@ -183,6 +188,7 @@ export function buildNotStartedComment(opts: { gitlabBaseUrl: string; projectPat
     `---`,
     '',
     `<sub>Generated by Maestro · [View MR →](${mrUrl})</sub>`,
+    ...(opts.marker === undefined ? [] : [``, `${reviewMarker(opts.marker.sha, opts.marker.flow)}`]),
   ].join('\n')
 }
 
@@ -230,14 +236,17 @@ export function getTurnErrorMessage(handle: unknown): string | undefined {
 
 /**
  * Resolve the model to use for an automated review. Priority: per-project
- * override > global reviewModel > DSH default (`fallback`).
+ * override > global reviewModel (Maestro Settings) > row-config reviewModel
+ * (lets a headless profile such as reviewer-ci pin a model from env vars,
+ * where there is no Settings UI) > DSH default (`fallback`).
  */
 export function resolveReviewModel(
   userConfig: MaestroUserConfig,
-  mapping: { reviewModel?: ReviewModelSelection | null } & Record<string, unknown> | undefined,
+  mapping: { reviewModel?: ReviewModelSelection | null; projectPath?: string } | undefined,
   fallback: ModelSelection,
+  rowSelection?: ReviewModelSelection | null,
 ): ModelSelection {
-  const raw = (mapping?.reviewModel as ReviewModelSelection | null | undefined) ?? userConfig.reviewModel
+  const raw = (mapping?.reviewModel as ReviewModelSelection | null | undefined) ?? userConfig.reviewModel ?? rowSelection
   if (raw === undefined || raw === null) return fallback
   return {
     provider: raw.provider,
@@ -246,6 +255,17 @@ export function resolveReviewModel(
   }
 }
 
+/** Effective auto-trigger flags: per-project row overrides global, unset inherits (design §4). */
+export function resolveReviewTriggers(
+  userConfig: MaestroUserConfig,
+  mapping?: ProjectMapping,
+): { onPush: boolean; onAssign: boolean } {
+  return {
+    onPush: mapping?.rereviewOnPush ?? userConfig.autoRereviewOnPush ?? false,
+    onAssign: mapping?.reviewOnAssign ?? userConfig.autoReviewOnAssign ?? true,
+  }
+}
+
 /** Compose a newly-created agent from the preset service owned by the root context. */
 export async function mountAgentPreset(
   agentPresets: { mount(agentCtx: Context, id: string): Promise<unknown> | unknown },
@@ -266,6 +286,19 @@ export interface Config {
   botUsername: string
   /** Hard ceiling on one automated agent's turn. */
   agentTimeoutMs: number
+  /**
+   * Deployment-level model pin, below Maestro Settings in precedence. Lets a
+   * headless profile (reviewer-ci) select the review model from env vars —
+   * e.g. REVIEW_MODEL_PROVIDER/REVIEW_MODEL — where no Settings UI exists.
+   *
+   * Deliberately absent from the zod schema below: schemastery object schemas
+   * always descend into inner fields (probed — even `.required(false)` still
+   * throws on undefined), so declaring it would fail every boot without the
+   * vars. Unknown keys pass validation through (same precedent as mapping-level
+   * reviewModel, which the projectMappings schema doesn't declare either),
+   * and resolveReviewModel reads it at review time.
+   */
+  reviewModel?: ReviewModelSelection | null
 }
 
 export const DEFAULT_AGENT_TIMEOUT_MS = 20 * 60_000
@@ -434,7 +467,7 @@ function normalizedDiffPath(path: string): string {
 export async function postReviewFindings(findings: ReviewFinding[], config: GitlabFindingPoster): Promise<void> {
   const fetcher = config.fetcher ?? fetch
   const apiBase = `${config.baseUrl}/api/v4/projects/${config.projectId}/merge_requests/${config.mrIid}`
-  const headers = { 'PRIVATE-TOKEN': config.token, 'Content-Type': 'application/json' }
+  const headers = { ...gitlabAuthHeaders(config.token), 'Content-Type': 'application/json' }
   for (const finding of findings) {
     let response: Response
     const label = severityPrefix(finding.severity)
@@ -546,6 +579,63 @@ export function auditorOutputFromSession(session: unknown) {
 }
 
 /** Full review + performance audit; resolves to the comment body that was posted. */
+/** Marker for CI-posted comments; webhook payloads carry no headSha and stay marker-free. */
+function commentMarker(payload: ReviewRequest): { sha: string; flow: ReviewFlow } | undefined {
+  if (payload.headSha === undefined) return undefined
+  return { sha: payload.headSha, flow: resolveFlow(payload.mode) }
+}
+
+/** CI-deep decision: deep mode + CI env + head SHA (spec §3). Mapping is checked by the caller. */
+export function shouldCiDeepReview(payload: ReviewRequest): boolean {
+  return payload.mode === 'deep'
+    && payload.headSha !== undefined
+    && process.env.SOURCE_PROJECT_ID !== undefined
+    && process.env.MR_IID !== undefined
+}
+
+/** CI quick-with-profile decision: quick mode + non-generic profile + CI env
+ *  + head SHA. Quick + generic/unset stays diff-only (no clone cost); a real
+ *  profile opts into the clone branch reviewer-only (no auditor — quick never
+ *  audits, see shouldAudit in runReviewAndAudit). Mapping is checked by the caller. */
+export function shouldCiQuickProfileReview(payload: ReviewRequest): boolean {
+  return payload.mode === 'quick'
+    && payload.reviewProfile !== undefined
+    && payload.reviewProfile !== 'generic'
+    && payload.headSha !== undefined
+    && process.env.SOURCE_PROJECT_ID !== undefined
+    && process.env.MR_IID !== undefined
+}
+
+/** Auditor degrade for CI (no runtime env): a govard throw becomes reviewer-only, never a failed review. */
+export function withAuditorDegrade(
+  runAuditor: (worktreePath: string, payload: ReviewRequest) => Promise<string>,
+): (worktreePath: string, payload: ReviewRequest) => Promise<string> {
+  return async (worktreePath, payload) => {
+    try {
+      return await runAuditor(worktreePath, payload)
+    } catch {
+      return 'Auditor skipped — no runtime environment in CI (reviewer-only review).'
+    }
+  }
+}
+
+/**
+ * Auditor instruction. The mapped flow keeps the full environment + test-suite
+ * workflow; the CI flow has no runtime, so the prompt countermands the
+ * auditor preset's environment steps and drops the Environment & Test Suite
+ * section entirely instead of reporting it "blocked".
+ */
+export function buildAuditorPrompt(opts: { staticOnly: boolean }): string {
+  if (!opts.staticOnly) {
+    return 'Audit this merge request\'s performance: bring up the environment, run the test suite, look for regressions, then write a Markdown report and tear the environment down.'
+  }
+  return 'Audit this merge request\'s performance from the static diff and checked-out code only. '
+    + 'No runtime environment exists in this container: ignore the auditor preset\'s environment steps '
+    + '(do not bring anything up, do not run the test suite, do not tear anything down). '
+    + 'Look for regressions by static analysis (diff, dependencies, query/shape risks), then write a Markdown report '
+    + 'and OMIT the Environment & Test Suite section entirely — never report it as blocked.'
+}
+
 export async function runReviewAndAudit(payload: ReviewRequest, deps: ReviewAndAuditDeps): Promise<string> {
   assertSafeId(payload.projectId, 'projectId')
   assertSafeId(payload.mrIid, 'mrIid')
@@ -581,6 +671,7 @@ export async function runReviewAndAudit(payload: ReviewRequest, deps: ReviewAndA
               summary: summaryText,
               failures,
               findings: { newCount, replyCount, severityCounts },
+              marker: commentMarker(payload),
             })
           : `## 🤖 Maestro Review\n\n**\`${payload.projectPath}\` !${payload.mrIid}** · ✅ Completed · \`${payload.mode}\`${(deps as unknown as { reviewProfile?: string }).reviewProfile !== undefined ? ` · \`${(deps as unknown as { reviewProfile: string }).reviewProfile}\`` : ''}\n\n${summaryText}${failures.length > 0 ? `\n\n<details>\n<summary>⚠️ Failed to post (${failures.length})</summary>\n\n${failures.map((f) => `- \`${f}\``).join('\n')}\n\n</details>` : ''}`
         sections.push(richOpts)
@@ -597,7 +688,8 @@ export async function runReviewAndAudit(payload: ReviewRequest, deps: ReviewAndA
       try {
         if (payload.scope.kind === 'discussion') await deps.replyToDiscussion(payload.scope.discussionId, body)
         else await deps.postComment(body)
-      } catch {
+      } catch (err) {
+        console.error(`maestro-orchestrator: posting review comment failed: ${err instanceof Error ? err.message : String(err)}`)
         await deps.writeFailedReport(payload.mrIid, body)
       }
       return body
@@ -632,13 +724,15 @@ export async function runDiffOnlyReview(payload: ReviewRequest, deps: DiffOnlyRe
           summary: summary ?? '',
           failures,
           isDiffOnly: true,
+          marker: commentMarker(payload),
         })
       : `## 🤖 Maestro Review — Diff-only\n\n> **Scope:** Diff-only — reviewed the GitLab diff without a local checkout, Magento environment, static analysis, or tests. For a full review, add this project in Settings → Maestro and mention again.\n\n${summary}${failures.length > 0 ? `\n\n<details>\n<summary>⚠️ Failed to post (${failures.length})</summary>\n\n${failures.map((f) => `- \`${f}\``).join('\n')}\n\n</details>` : ''}`
     const body = diffBody
     try {
       if (payload.scope.kind === 'discussion') await deps.replyToDiscussion(payload.scope.discussionId, body)
       else await deps.postComment(body)
-    } catch {
+    } catch (err) {
+      console.error(`maestro-orchestrator: posting review comment failed: ${err instanceof Error ? err.message : String(err)}`)
       await deps.writeFailedReport(payload.mrIid, body)
     }
     return body
@@ -657,13 +751,14 @@ export async function declineUnmappedDeepReview(payload: ReviewRequest, deps: Re
   const depsWithUrl = deps as unknown as { gitlabBaseUrl?: string; projectPath?: string }
   const baseUrl = depsWithUrl.gitlabBaseUrl
   const body = baseUrl !== undefined
-    ? buildNotStartedComment({ gitlabBaseUrl: baseUrl, projectPath: payload.projectPath, mrIid: payload.mrIid })
+    ? buildNotStartedComment({ gitlabBaseUrl: baseUrl, projectPath: payload.projectPath, mrIid: payload.mrIid, marker: commentMarker(payload) })
     : '## 🤖 Maestro Review — Not started\n\n**`' + payload.projectPath + '` !' + payload.mrIid + '** · ⏸️ Not started\n\n> Deep review requires a project mapping with a local checkout and Magento environment.\n> Add this project in **Settings → Maestro**, then mention the reviewer again.'
   try {
     try {
       if (payload.scope.kind === 'discussion') await deps.replyToDiscussion(payload.scope.discussionId, body)
       else await deps.postComment(body)
-    } catch {
+    } catch (err) {
+      console.error(`maestro-orchestrator: posting review comment failed: ${err instanceof Error ? err.message : String(err)}`)
       await deps.writeFailedReport(payload.mrIid, body)
     }
   } finally {
@@ -731,7 +826,7 @@ export async function fetchMrBaseSha(
   try {
     const response = await fetcher(
       `${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}`,
-      { headers: { 'PRIVATE-TOKEN': token } },
+      { headers: gitlabAuthHeaders(token) },
     )
     if (!response.ok) return undefined
     const mr = await response.json() as { diff_refs?: { base_sha?: string } }
@@ -1039,7 +1134,7 @@ export function apply(ctx: Context, config: Config): void {
     }
   }
 
-  async function runAuditor(worktreePath: string, payload: ReviewRequest, effective: { gitlabBaseUrl: string; gitlabToken: string; botUsername: string }, modelSelection?: ModelSelection): Promise<string> {
+  async function runAuditor(worktreePath: string, payload: ReviewRequest, effective: { gitlabBaseUrl: string; gitlabToken: string; botUsername: string }, modelSelection?: ModelSelection, opts?: { staticOnly?: boolean }): Promise<string> {
     let handle: AgentHandle
     const agentOptions = agentOptionsForModel(modelSelection ?? ctx.agentDefaultModel.currentSelection())
     try {
@@ -1066,7 +1161,7 @@ export function apply(ctx: Context, config: Config): void {
     }
     ctx.sessionTitle.rename(handle.agent.session, `Maestro Auditor — MR !${payload.mrIid} (${payload.projectPath})`)
     try {
-      const prompt = 'Audit this merge request\'s performance: bring up the environment, run the test suite, look for regressions, then write a Markdown report and tear the environment down.'
+      const prompt = buildAuditorPrompt({ staticOnly: opts?.staticOnly === true })
       handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: prompt }], source: { kind: 'user' } }))
       await whenIdleWithTimeout(handle, effectiveAgentTimeoutMs)
       const output = auditorOutputFromSession(handle.agent.session)
@@ -1077,8 +1172,9 @@ export function apply(ctx: Context, config: Config): void {
     }
   }
 
-  ctx.on('maestro/review-request', (payload) => {
-    void (async () => {
+  async function runReview(payload: ReviewRequest): Promise<ReviewResult> {
+    const t0 = Date.now()
+    try {
       const userConfig = await loadUserConfig()
       const effective = {
         gitlabBaseUrl: userConfig.gitlabBaseUrl ?? config.gitlabBaseUrl,
@@ -1096,16 +1192,37 @@ export function apply(ctx: Context, config: Config): void {
         })
       }
       const mapping = effective.projectMappings.find(m => m.projectPath === payload.projectPath)
+      // CI-deep (spec §3): unmapped deep review with CI env + head SHA skips
+      // both the decline and the diff-only fallback and runs the clone branch
+      // below, which shares the mapped path's completion tail.
+      const ciDeep = mapping === undefined && payload.mode === 'deep' && shouldCiDeepReview(payload)
+      // CI quick-with-profile: unmapped quick + non-generic profile + CI env
+      // skips the diff-only fallback and joins the clone branch below, which
+      // runs reviewer-only (quick never audits).
+      const ciQuickProfile = mapping === undefined && shouldCiQuickProfileReview(payload)
       // Unmapped reviewer assignments remain no-ops. Only an explicit mention
       // may opt into the intentionally limited, diff-only fallback below.
-      if (mapping === undefined && payload.trigger !== 'mention') return
+      if (mapping === undefined && payload.trigger !== 'mention') {
+        return { ok: true, failures: [], durationMs: Date.now() - t0 }
+      }
+      const triggers = resolveReviewTriggers(userConfig, mapping)
+      // Gated-off auto-triggers stay fully silent: no history, no signals, no comment.
+      if (payload.trigger === 'reviewer-assignment' && !triggers.onAssign) {
+        return { ok: true, failures: [], durationMs: Date.now() - t0 }
+      }
+      if (payload.trigger === 'push' && !triggers.onPush) {
+        return { ok: true, failures: [], durationMs: Date.now() - t0 }
+      }
       // A push only re-reviews an MR that already has a completed review;
       // otherwise every newly opened MR would be reviewed twice.
-      if (payload.trigger === 'push' && !(await hasCompletedReview(payload.projectId, payload.mrIid))) return
+      if (payload.trigger === 'push' && !(await hasCompletedReview(payload.projectId, payload.mrIid))) {
+        return { ok: true, failures: [], durationMs: Date.now() - t0 }
+      }
       const { gitlabToken } = effective
       if (gitlabToken === undefined) {
-        console.error(`maestro-orchestrator: MR !${String(payload.mrIid)} for project ${payload.projectPath} has no GitLab token — set one in Maestro Settings or MAESTRO_GITLAB_TOKEN`)
-        return
+        const message = `MR !${String(payload.mrIid)} for project ${payload.projectPath} has no GitLab token — set one in Maestro Settings or MAESTRO_GITLAB_TOKEN`
+        console.error(`maestro-orchestrator: ${message}`)
+        return { ok: false, failures: [message], durationMs: Date.now() - t0 }
       }
       const resolved = { ...effective, gitlabToken }
       const historyId = `${payload.projectId}-${payload.mrIid}-${Date.now()}`
@@ -1136,7 +1253,7 @@ export function apply(ctx: Context, config: Config): void {
       const fallbackSelection: ModelSelection = (ctx.get?.('agentDefaultModel') as { currentSelection(): ModelSelection } | undefined)?.currentSelection()
         ?? (ctx as unknown as { agentDefaultModel?: { currentSelection(): ModelSelection } }).agentDefaultModel?.currentSelection()
         ?? { provider: 'fallback', model: 'fallback' }
-      const reviewModelSelection = resolveReviewModel(userConfig, mapping, fallbackSelection)
+      const reviewModelSelection = resolveReviewModel(userConfig, mapping, fallbackSelection, config.reviewModel)
       // Opt-in Telegram digest; a delivery failure is logged and dropped.
       const reviewStartMsOuter = Date.now()
       const notifyTelegram = (
@@ -1194,7 +1311,7 @@ export function apply(ctx: Context, config: Config): void {
           `${resolved.gitlabBaseUrl}/api/v4/projects/${payload.projectId}/merge_requests/${payload.mrIid}/notes`,
           {
             method: 'POST',
-            headers: { 'PRIVATE-TOKEN': resolved.gitlabToken, 'Content-Type': 'application/json' },
+            headers: { ...gitlabAuthHeaders(resolved.gitlabToken), 'Content-Type': 'application/json' },
             body: JSON.stringify({ body }),
           },
         )
@@ -1205,23 +1322,25 @@ export function apply(ctx: Context, config: Config): void {
           `${resolved.gitlabBaseUrl}/api/v4/projects/${payload.projectId}/merge_requests/${payload.mrIid}/discussions/${encodeURIComponent(discussionId)}/notes`,
           {
             method: 'POST',
-            headers: { 'PRIVATE-TOKEN': resolved.gitlabToken, 'Content-Type': 'application/json' },
+            headers: { ...gitlabAuthHeaders(resolved.gitlabToken), 'Content-Type': 'application/json' },
             body: JSON.stringify({ body }),
           },
         )
         if (!response.ok) throw new Error(`GitLab API error ${response.status}: ${await response.text()}`)
       }
       try {
-        if (mapping === undefined) {
-          if (payload.mode === 'deep') {
+        if (mapping === undefined && !ciDeep && !ciQuickProfile) {
+          // CI-deep (spec §3) skips the decline and falls through to the clone
+          // branch below; every other unmapped deep review still declines here.
+          if (payload.mode === 'deep' && !shouldCiDeepReview(payload)) {
             await declineUnmappedDeepReview(payload, { postComment, replyToDiscussion, writeFailedReport, gitlabBaseUrl: resolved.gitlabBaseUrl } as unknown as ReviewCommentDeps)
             await recordReviewFinish(historyId, { status: 'completed', summary: 'Deep review declined (unmapped project)' })
             notifyTelegram('completed', 'Deep review declined (unmapped project)')
             await signals?.finish('completed')
-            return
+            return { ok: true, summary: 'Deep review declined (unmapped project)', failures: [], durationMs: Date.now() - t0 }
           }
           const diffBody = await runDiffOnlyReview(payload, {
-            runReviewer: (p) => runReviewer(undefined, p, resolved, undefined, reviewModelSelection, incrementalBlock),
+            runReviewer: (p) => runReviewer(undefined, p, resolved, payload.reviewProfile, reviewModelSelection, incrementalBlock),
             postComment,
             replyToDiscussion,
             writeFailedReport,
@@ -1230,9 +1349,47 @@ export function apply(ctx: Context, config: Config): void {
           await recordReviewFinish(historyId, { status: 'completed', summary: summarize(diffBody) })
           notifyTelegram('completed', summarize(diffBody))
           await signals?.finish('completed')
-          return
+          return { ok: true, summary: summarize(diffBody), failures: [], durationMs: Date.now() - t0 }
         }
         let fullBody: string
+        if (ciDeep || ciQuickProfile) {
+          // CI-deep (mapping is always undefined here — the unmapped block above
+          // returned for every other case): clone the source at the head SHA,
+          // map it in memory, and reuse the mapped machinery reviewer-only.
+          // CI quick-with-profile joins the same branch; runReviewAndAudit skips
+          // the auditor for quick (shouldAudit), so it stays reviewer-only.
+          // No govard/vendor linking (ciEnsureWorktree is plain fetch + worktree).
+          const ciHost = process.env.GITLAB_HOST?.trim() || new URL(resolved.gitlabBaseUrl).hostname
+          const cloneDir = join('/tmp', `maestro-ci-src-${payload.projectId}-${payload.mrIid}`)
+          await cloneSourceRepo({ fetcher: fetch, run: defaultRun, host: ciHost, projectId: payload.projectId, sourceBranch: payload.sourceBranch, headSha: payload.headSha as string, token: resolved.gitlabToken, dir: cloneDir })
+          try {
+            const ciEnsureWorktree = async (repoPath: string, branch: string, pid: number, iid: number, suffix?: string): Promise<string> => {
+              assertSafeBranchName(branch)
+              const wt = join('/tmp', `maestro-mr-${pid}-${iid}${suffix === undefined ? '' : `-${suffix}`}`)
+              await defaultRun('git', ['fetch', '--depth', '50', 'origin', branch], repoPath)
+              await defaultRun('git', ['worktree', 'remove', '--force', wt], repoPath).catch(() => {})
+              await defaultRun('git', ['worktree', 'add', '--detach', '--', wt, payload.headSha as string], repoPath)
+              return wt
+            }
+            fullBody = await runReviewAndAudit(payload, {
+              localRepoPath: cloneDir,
+              ensureWorktree: ciEnsureWorktree,
+              removeWorktree,
+              runReviewer: (worktreePath, p) => runReviewer(worktreePath, p, resolved, payload.reviewProfile ?? 'generic', reviewModelSelection, incrementalBlock),
+              runAuditor: withAuditorDegrade((worktreePath, p) => runAuditor(worktreePath, p, resolved, reviewModelSelection, { staticOnly: true })),
+              postComment,
+              replyToDiscussion,
+              writeFailedReport,
+              gitlabBaseUrl: resolved.gitlabBaseUrl,
+              reviewProfile: payload.reviewProfile ?? 'generic',
+            } as unknown as ReviewAndAuditDeps)
+          } finally {
+            await defaultRun('rm', ['-rf', cloneDir]).catch(() => {})
+          }
+        } else {
+        // Unreachable when mapping is undefined: the unmapped block returned
+        // for every non-CI-deep case, and ciDeep took the branch above.
+        if (mapping === undefined) throw new Error('unreachable: unmapped review without CI-deep decision')
         try {
           fullBody = await runReviewAndAudit(payload, {
             localRepoPath: mapping.localRepoPath,
@@ -1250,7 +1407,7 @@ export function apply(ctx: Context, config: Config): void {
           const isBranchNotFound = (err as { code?: string })?.code === 'BRANCH_NOT_FOUND' || isBranchNotFoundError(err)
           if (isBranchNotFound) {
             const diffBody = await runDiffOnlyReview(payload, {
-              runReviewer: (p) => runReviewer(undefined, p, resolved, undefined, reviewModelSelection, incrementalBlock),
+              runReviewer: (p) => runReviewer(undefined, p, resolved, payload.reviewProfile, reviewModelSelection, incrementalBlock),
               postComment,
               replyToDiscussion,
               writeFailedReport,
@@ -1261,25 +1418,33 @@ export function apply(ctx: Context, config: Config): void {
             await recordReviewFinish(historyId, { status: 'completed', summary: branchNote })
             notifyTelegram('completed', branchNote)
             await signals?.finish('completed')
-            return
+            return { ok: true, summary: branchNote, failures: [], durationMs: Date.now() - t0 }
           }
           throw err
         }
+        }
         await recordReviewFinish(historyId, { status: 'completed', summary: summarize(fullBody) })
         notifyTelegram('completed', summarize(fullBody))
         await signals?.finish('completed')
+        return { ok: true, summary: summarize(fullBody), failures: [], durationMs: Date.now() - t0 }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)
         await recordReviewFinish(historyId, { status: 'failed', error: message }).catch(() => {})
         notifyTelegram('failed', message)
         await signals?.finish('failed')
-        throw err
+        return { ok: false, summary: undefined, failures: [message], durationMs: Date.now() - t0 }
       }
-    })().catch((err: unknown) => {
+    } catch (err) {
       // Worktree creation, agent creation, and fallback delivery all run from
-      // an event callback, so surface failures rather than leaking a rejected
-      // fire-and-forget Promise.
+      // this function — surface failures as a result instead of an unhandled
+      // rejection, so both the fire-and-forget webhook path and an awaiting
+      // CI caller observe the same outcome.
+      const message = err instanceof Error ? err.message : String(err)
       console.error(`maestro-orchestrator: review run failed for MR !${String(payload.mrIid)}:`, err)
-    })
-  })
+      return { ok: false, summary: undefined, failures: [message], durationMs: Date.now() - t0 }
+    }
+  }
+
+  ctx.on('maestro/review-request', (payload) => { void runReview(payload) })
+  ctx.provide('reviewRunner', runReview)
 }

package/src/host/providers/ci-trigger.ts

@@ -0,0 +1,164 @@
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { join } from 'node:path'
+import type { ReviewRequest, ReviewResult } from '../events.js'
+import { lastCompletedReview } from '../review-history.js'
+import type { ReviewSkillProfile } from '../skills-tool.js'
+import { gitlabAuthHeaders } from '../gitlab-auth.js'
+import { hasCompletedReviewForSha, hasRunningEyes } from '../ci-coexist.js'
+
+export const name = 'maestro-review-ci-trigger'
+export const inject = ['reviewRunner'] as const
+
+const REVIEW_PROFILES = ['magento2', 'laravel', 'symfony', 'wordpress', 'generic'] as const
+
+export interface CiEnvConfig {
+  gitlabBaseUrl: string
+  gitlabToken: string
+  sourceProjectId: number
+  mrIid: number
+  mode: 'quick' | 'deep'
+  dryRun: boolean
+  reviewProfile?: ReviewSkillProfile
+  /** Mirror of Settings UI autoRereviewOnPush (default off): re-review new pushes. */
+  rereviewOnPush: boolean
+}
+
+export const CiEnvConfig: z<CiEnvConfig> = z.object({
+  gitlabBaseUrl: z.string().required(),
+  gitlabToken: z.string().role('secret').required(),
+  sourceProjectId: z.number().required(),
+  mrIid: z.number().required(),
+  mode: z.union([z.const('quick'), z.const('deep')]).default('quick'),
+  dryRun: z.boolean().default(false),
+  reviewProfile: z.union([z.const('magento2'), z.const('laravel'), z.const('symfony'), z.const('wordpress'), z.const('generic')]),
+  rereviewOnPush: z.boolean().default(false),
+})
+
+/**
+ * Reads the CI contract env vars (spec §5.2) — not Cordis-supplied config, since these are
+ * per-run values a static profile config cannot hold. schemastery's `.required()` only rejects
+ * `undefined`, not an empty string, so GITLAB_HOST/MAESTRO_GITLAB_TOKEN presence is checked here
+ * before defaulting to `''` — otherwise a missing env var would silently pass validation.
+ */
+export function parseCiEnvConfig(env: Record<string, string | undefined>): CiEnvConfig {
+  if (env.GITLAB_HOST === undefined) throw new Error('missing GITLAB_HOST')
+  if (env.MAESTRO_GITLAB_TOKEN === undefined) throw new Error('missing MAESTRO_GITLAB_TOKEN')
+  if (env.REVIEW_PROFILE !== undefined && !(REVIEW_PROFILES as readonly string[]).includes(env.REVIEW_PROFILE)) {
+    throw new Error(`unsupported REVIEW_PROFILE "${env.REVIEW_PROFILE}" (supported: ${REVIEW_PROFILES.join(', ')})`)
+  }
+  return CiEnvConfig({
+    gitlabBaseUrl: `https://${env.GITLAB_HOST}`,
+    gitlabToken: env.MAESTRO_GITLAB_TOKEN,
+    sourceProjectId: Number(env.SOURCE_PROJECT_ID),
+    mrIid: Number(env.MR_IID),
+    mode: env.REVIEW_MODE === 'deep' ? 'deep' : 'quick',
+    dryRun: env.REVIEW_DRY_RUN === '1',
+    reviewProfile: env.REVIEW_PROFILE as ReviewSkillProfile | undefined,
+    rereviewOnPush: env.REVIEW_ON_PUSH === '1',
+  })
+}
+
+/** The one field a webhook payload carries that env vars don't — orchestrator fetches the diff itself. */
+export async function fetchMrSourceBranch(config: CiEnvConfig, fetcher: typeof fetch = fetch): Promise<string> {
+  return (await fetchMrDetail(config, fetcher)).sourceBranch
+}
+
+/** MR detail pieces CI needs in one call: source branch (worktree) + head SHA (push-gate). */
+export async function fetchMrDetail(config: CiEnvConfig, fetcher: typeof fetch = fetch): Promise<{ sourceBranch: string; headSha: string }> {
+  const url = `${config.gitlabBaseUrl}/api/v4/projects/${config.sourceProjectId}/merge_requests/${config.mrIid}`
+  const res = await fetcher(url, { headers: gitlabAuthHeaders(config.gitlabToken) })
+  if (!res.ok) throw new Error(`GitLab API error ${res.status}: ${await res.text()}`)
+  const body = await res.json() as { source_branch?: string; sha?: string }
+  if (typeof body.source_branch !== 'string') throw new Error('GitLab merge request response is missing source_branch')
+  if (typeof body.sha !== 'string') throw new Error('GitLab merge request response is missing sha')
+  return { sourceBranch: body.source_branch, headSha: body.sha }
+}
+
+export async function runCiTrigger(
+  ctx: Context,
+  config: CiEnvConfig,
+  deps: {
+    fetcher?: typeof fetch
+    writeFile?: typeof import('node:fs/promises').writeFile
+    history?: { lastCompletedReview(projectId: number, mrIid: number): Promise<{ headSha?: string } | undefined> }
+  } = {},
+): Promise<ReviewResult> {
+  const { sourceBranch, headSha } = await fetchMrDetail(config, deps.fetcher)
+  // Push-gate (mirror of the webhook autoRereviewOnPush semantics): the bridge fires
+  // on every MR pipeline, so skip when this exact head SHA already completed — and
+  // skip new pushes too unless REVIEW_ON_PUSH=1. A re-run then gets the H6 incremental
+  // block from history for free. Cache miss (no history) fails open toward running.
+  const history = deps.history ?? { lastCompletedReview }
+  const prior = await history.lastCompletedReview(config.sourceProjectId, config.mrIid)
+  let result: ReviewResult
+  if (prior?.headSha === headSha) {
+    result = { ok: true, summary: `already reviewed at ${headSha}, skipping`, failures: [], durationMs: 0 }
+  } else if (prior !== undefined && !config.rereviewOnPush) {
+    result = { ok: true, summary: `new commits since ${prior.headSha} but REVIEW_ON_PUSH is not set, skipping`, failures: [], durationMs: 0 }
+  } else {
+    // Coexistence (CI yields to webhook): the CI history store is invisible to
+    // the webhook flow and vice versa, so check the MR itself for a completed
+    // review marker of this SHA or an in-flight eyes marker before booting.
+    const coFetcher = deps.fetcher ?? fetch
+    if (await hasCompletedReviewForSha(coFetcher, config.gitlabBaseUrl, config.gitlabToken, config.sourceProjectId, config.mrIid, headSha)) {
+      result = { ok: true, summary: `webhook already reviewed ${headSha} — skipping`, failures: [], durationMs: 0 }
+    } else if (await hasRunningEyes(coFetcher, config.gitlabBaseUrl, config.gitlabToken, config.sourceProjectId, config.mrIid)) {
+      result = { ok: true, summary: 'another review is running — skipping', failures: [], durationMs: 0 }
+    } else {
+    // projectPath is synthetic (no webhook payload to read it from) — harmless: the
+    // reviewer-ci profile's own projectMappings is always [], so orchestrator's
+    // mapping lookup on projectPath never matches regardless of its exact value
+    // (same precedent as the PR #52 runner it replaces).
+    const request: ReviewRequest = {
+      projectPath: `project/${config.sourceProjectId}`,
+      projectId: config.sourceProjectId,
+      mrIid: config.mrIid,
+      sourceBranch,
+      headSha,
+      trigger: 'mention',
+      mode: config.mode,
+      scope: { kind: 'mr' },
+      reviewProfile: config.reviewProfile,
+    }
+    result = await ctx.reviewRunner(request)
+    }
+  }
+  const { writeFile } = deps.writeFile !== undefined ? { writeFile: deps.writeFile } : await import('node:fs/promises')
+  // entrypoint.sh cds into deepseek-harness before execing dsh, so a bare relative
+  // path would land inside the harness checkout (lost with the container). The
+  // entrypoint exports REVIEW_REPORT_DIR=$PWD captured before the cd, so reports land
+  // in the CI job's working directory where `artifacts:` picks them up.
+  const reportDir = process.env.REVIEW_REPORT_DIR?.trim() || '.'
+  const report = { ...result, projectId: config.sourceProjectId, mrIid: config.mrIid, mode: config.mode, generatedAt: new Date().toISOString() }
+  await writeFile(join(reportDir, 'review-report.json'), JSON.stringify(report, null, 2), 'utf-8')
+  const md = `# Review Report\n\n**Project:** ${config.sourceProjectId} !${config.mrIid}\n**Mode:** ${config.mode}\n**Duration:** ${result.durationMs}ms\n\n${result.summary ?? '(no summary)'}\n${result.failures.length > 0 ? `\nFailures:\n${result.failures.map(f => `- ${f}`).join('\n')}\n` : ''}`
+  await writeFile(join(reportDir, 'review-report.md'), md, 'utf-8')
+  return result
+}
+
+export function apply(ctx: Context): void {
+  ctx.effect(() => {
+    void (async () => {
+      try {
+        const config = parseCiEnvConfig(process.env)
+        console.log(`[review] ci-trigger starting: project ${config.sourceProjectId} !${config.mrIid} mode=${config.mode} dryRun=${config.dryRun}`)
+        const result = config.dryRun
+          ? { ok: true, summary: '[dry-run] config valid, skipping review', failures: [], durationMs: 0 }
+          : await runCiTrigger(ctx, config)
+        console.log(`[review] ci-trigger finished: ok=${result.ok} summary=${JSON.stringify(result.summary)} failures=${result.failures.length}`)
+        for (const failure of result.failures) console.error(`[review] ci-trigger failure: ${failure}`)
+        const exit = ctx.get('appExit')
+        if (exit === undefined) {
+          console.error('[review] ctx.get(\'appExit\') is undefined — the launcher did not provide it, process cannot signal its real exit code')
+        } else {
+          exit(result.ok ? 0 : 1)
+        }
+      } catch (err) {
+        console.error('maestro-review-ci-trigger:', err instanceof Error ? err.message : String(err))
+        ctx.get('appExit')?.(1)
+      }
+    })()
+    return () => {}
+  }, 'maestro-review-ci-trigger run')
+}

package/src/host/providers/gitlab.ts

@@ -128,7 +128,8 @@ export function apply(ctx: Context, config: Config): void {
         let body: GitlabMrWebhookBody; try { body = JSON.parse(raw) } catch { res.writeHead(400).end(); return }
         const userConfig = await loadUserConfig()
         if ((body.object_kind === 'merge_request' || body.object_kind === 'note') && !hasValidGitlabMrIdentity(body)) { res.writeHead(400).end(); return }
-        const request = routeGitlabReviewRequest(body, userConfig.botUsername ?? config.botUsername ?? 'maestro', { pushEnabled: userConfig.autoRereviewOnPush === true })
+        // The orchestrator is the sole push gate (resolveReviewTriggers); intake always emits.
+        const request = routeGitlabReviewRequest(body, userConfig.botUsername ?? config.botUsername ?? 'maestro', { pushEnabled: true })
         if (request !== undefined) ctx.emit('maestro/review-request', request)
         res.writeHead(200).end()
       })