@ddtcorex/dsh-maestro-review 0.5.0 → 0.6.0

package/profiles/reviewer-ci/pnpm-workspace.yaml

@@ -7,6 +7,17 @@
 # printed "Scope: all 2 workspace projects" and resolved relative to `../..`
 # without this file present).
 packages: []
+# Postinstall scripts required at runtime (node-pty/subprocess-local spawn
+# agents, koffi/protobufjs/genai serve model IO). Exact versions pinned in
+# pnpm-lock.yaml; review on every profile dep bump.
+allowBuilds:
+  '@deepseek-ai/dsh-subprocess-local': true
+  '@google/genai': true
+  koffi: true
+  node-pty: true
+  protobufjs: true
 minimumReleaseAgeExclude:
   - '@ddtcorex/dsh-maestro-review@0.3.1'
   - '@ddtcorex/maestro-skills@2.11.0'
+  - '@ddtcorex/dsh-maestro-review@0.5.1'
+  - '@ddtcorex/maestro-skills@2.11.1'

package/src/host/ci-coexist.ts

@@ -2,10 +2,12 @@ import { gitlabAuthHeaders } from './gitlab-auth.js'
 import { parseReviewMarker } from './review-marker.js'
 
 /**
- * Coexistence checks (spec §4): the CI flow yields to any completed review of
- * the same head SHA (whatever flow posted it) and to an in-flight review
- * (eyes running-marker). Fetch failures fail open toward running — a missing
- * signal must never block a review, only a present one skips it.
+ * Coexistence checks (spec §4): the CI flow yields to a completed review of
+ * the same head SHA carrying a review marker (i.e. an earlier CI review —
+ * webhook reviews post marker-free and stay invisible here) and to an
+ * in-flight review (eyes running-marker). Fetch failures fail open toward
+ * running — a missing signal must never block a review, only a present one
+ * skips it.
  */
 export async function hasCompletedReviewForSha(
   fetcher: typeof fetch, baseUrl: string, token: string, projectId: number, mrIid: number, sha: string,

package/src/host/events.ts

@@ -30,6 +30,10 @@ export interface ReviewRequest extends MrOpenedPayload {
    * webhook producer never sets it — webhook comments stay marker-free.
    */
   headSha?: string
+  /** Short (8-char) head-sha hint for `push` triggers, taken from the webhook
+   * body — feeds the in-flight key so two concurrent pushes stop deduping
+   * each other. Absent when the body carries no sha. */
+  pushSha?: string
 }
 
 export interface ReviewResult {

package/src/host/gitlab-client.ts

@@ -47,6 +47,27 @@ export function selectFileDiff(diffs: GitlabDiff[], path: string): string | unde
   return `--- ${d.old_path}\n+++ ${d.new_path}\n${d.diff}`
 }
 
+/**
+ * `fetch` with a hard ceiling: aborts the request after `ms` (default 15s)
+ * and throws `GitLab API timeout after <ms>ms` on abort. The timer is always
+ * cleared on settle. Pre-agent lookups degrade the throw to `undefined` at
+ * their own call site; post-agent callers let it reach `writeFailedReport`.
+ */
+export async function fetchWithTimeout(
+  url: string, init: RequestInit | undefined, ms = 15_000,
+): Promise<Response> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), ms)
+  try {
+    return await fetch(url, { ...init, signal: controller.signal })
+  } catch (err) {
+    if ((err as Error)?.name === 'AbortError') throw new Error(`GitLab API timeout after ${ms}ms`)
+    throw err
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 interface GitlabDiffRefs {
   base_sha: string
   start_sha: string

package/src/host/incremental.ts

@@ -1,4 +1,5 @@
 import { gitlabAuthHeaders } from './gitlab-auth.js'
+import { fetchWithTimeout } from './gitlab-client.js'
 export interface CompareCommit {
   short_id?: string
   title?: string
@@ -56,7 +57,7 @@ export async function fetchMrDetailHeadSha(
   baseUrl: string, token: string, projectId: number, mrIid: number,
 ): Promise<string | undefined> {
   try {
-    const response = await fetch(
+    const response = await fetchWithTimeout(
       `${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}`,
       { headers: gitlabAuthHeaders(token) },
     )
@@ -73,7 +74,7 @@ export async function fetchCompare(
   baseUrl: string, token: string, projectId: number, from: string, to: string,
 ): Promise<CompareResult | undefined> {
   try {
-    const response = await fetch(
+    const response = await fetchWithTimeout(
       `${baseUrl}/api/v4/projects/${projectId}/repository/compare?from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}`,
       { headers: gitlabAuthHeaders(token) },
     )

package/src/host/orchestrator.ts

@@ -234,6 +234,22 @@ export function getTurnErrorMessage(handle: unknown): string | undefined {
   }
 }
 
+/**
+ * A turn can go idle without ever calling a tool when the model provider
+ * itself rejects the request (auth/billing/rate-limit) — `whenIdleWithTimeout`
+ * only guards against a hang, not this. Left unchecked, the reviewer's
+ * missing-skill-profile check and the auditor's empty-output path both treat
+ * this the same as "the agent just didn't call anything", misreporting a
+ * provider outage as a maestro-skills installation problem (or, for the
+ * auditor, as a silent clean pass). Surface the real turn error immediately.
+ */
+export function assertTurnSucceeded(handle: unknown): void {
+  const turnMsg = getTurnErrorMessage(handle)
+  if (turnMsg !== undefined) {
+    throw new Error(`Review turn failed before completing: ${turnMsg}`)
+  }
+}
+
 /**
  * Resolve the model to use for an automated review. Priority: per-project
  * override > global reviewModel (Maestro Settings) > row-config reviewModel
@@ -524,7 +540,8 @@ const inFlightKeys = new Set<string>()
 
 function reviewKey(payload: ReviewRequest): string {
   const scope = payload.scope.kind === 'mr' ? 'mr' : `discussion:${payload.scope.discussionId}`
-  return `${payload.projectId}:${payload.mrIid}:${payload.mode}:${scope}`
+  const sha = typeof payload.pushSha === 'string' && payload.pushSha !== '' ? `:${payload.pushSha}` : ''
+  return `${payload.projectId}:${payload.mrIid}:${payload.mode}:${scope}:${payload.trigger}${sha}`
 }
 
 /**
@@ -640,7 +657,10 @@ export async function runReviewAndAudit(payload: ReviewRequest, deps: ReviewAndA
   assertSafeId(payload.projectId, 'projectId')
   assertSafeId(payload.mrIid, 'mrIid')
   const key = reviewKey(payload)
-  if (inFlightKeys.has(key)) return ''
+  if (inFlightKeys.has(key)) {
+    console.error(`maestro-orchestrator: deduped duplicate in-flight review key=${key} trigger=${payload.trigger}`)
+    return ''
+  }
   inFlightKeys.add(key)
   try {
     const worktreePath = await deps.ensureWorktree(deps.localRepoPath, payload.sourceBranch, payload.projectId, payload.mrIid, reviewKeyHash(payload))
@@ -711,7 +731,10 @@ export async function runDiffOnlyReview(payload: ReviewRequest, deps: DiffOnlyRe
   assertSafeId(payload.projectId, 'projectId')
   assertSafeId(payload.mrIid, 'mrIid')
   const key = reviewKey(payload)
-  if (inFlightKeys.has(key)) return ''
+  if (inFlightKeys.has(key)) {
+    console.error(`maestro-orchestrator: deduped duplicate in-flight review key=${key} trigger=${payload.trigger}`)
+    return ''
+  }
   inFlightKeys.add(key)
   try {
     const { summary, failures } = await deps.runReviewer(payload)
@@ -741,12 +764,18 @@ export async function runDiffOnlyReview(payload: ReviewRequest, deps: DiffOnlyRe
   }
 }
 
-/** Decline a Deep request that lacks the local mapping it requires. */
-export async function declineUnmappedDeepReview(payload: ReviewRequest, deps: ReviewCommentDeps): Promise<void> {
+/** Decline a Deep request that lacks the local mapping it requires.
+ * Resolves `true` when the decline was posted, `false` when a duplicate
+ * in-flight review is already handling this key (caller must not record a
+ * completion for work it did not do). */
+export async function declineUnmappedDeepReview(payload: ReviewRequest, deps: ReviewCommentDeps): Promise<boolean> {
   assertSafeId(payload.projectId, 'projectId')
   assertSafeId(payload.mrIid, 'mrIid')
   const key = reviewKey(payload)
-  if (inFlightKeys.has(key)) return
+  if (inFlightKeys.has(key)) {
+    console.error(`maestro-orchestrator: deduped duplicate in-flight review key=${key} trigger=${payload.trigger}`)
+    return false
+  }
   inFlightKeys.add(key)
   const depsWithUrl = deps as unknown as { gitlabBaseUrl?: string; projectPath?: string }
   const baseUrl = depsWithUrl.gitlabBaseUrl
@@ -761,6 +790,7 @@ export async function declineUnmappedDeepReview(payload: ReviewRequest, deps: Re
       console.error(`maestro-orchestrator: posting review comment failed: ${err instanceof Error ? err.message : String(err)}`)
       await deps.writeFailedReport(payload.mrIid, body)
     }
+    return true
   } finally {
     inFlightKeys.delete(key)
   }
@@ -1067,6 +1097,7 @@ export function apply(ctx: Context, config: Config): void {
           source: { kind: 'user' },
         }))
         await whenIdleWithTimeout(handle, effectiveAgentTimeoutMs)
+        assertTurnSucceeded(handle)
         if (reviewProfile !== undefined && (reviewerContext === undefined || loadedReviewProfile(reviewerContext) !== reviewProfile)) {
           throw new Error(`reviewer did not successfully load the required ${reviewProfile} review skill profile; no findings were posted`)
         }
@@ -1164,6 +1195,7 @@ export function apply(ctx: Context, config: Config): void {
       const prompt = buildAuditorPrompt({ staticOnly: opts?.staticOnly === true })
       handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: prompt }], source: { kind: 'user' } }))
       await whenIdleWithTimeout(handle, effectiveAgentTimeoutMs)
+      assertTurnSucceeded(handle)
       const output = auditorOutputFromSession(handle.agent.session)
       const text = output.map(block => ('text' in block ? block.text : '')).join('')
       return `## Maestro Performance Audit\n\n${text}`
@@ -1203,25 +1235,29 @@ export function apply(ctx: Context, config: Config): void {
       // 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') {
+        console.error(`maestro-orchestrator: drop unmapped project=${payload.projectPath} mr=!${payload.mrIid} trigger=${payload.trigger}`)
         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.
+      // Gated-off auto-triggers stay fully silent: no history, no signals, no comment (host log only).
       if (payload.trigger === 'reviewer-assignment' && !triggers.onAssign) {
+        console.error(`maestro-orchestrator: drop assign-gate-off project=${payload.projectPath} mr=!${payload.mrIid} trigger=${payload.trigger}`)
         return { ok: true, failures: [], durationMs: Date.now() - t0 }
       }
       if (payload.trigger === 'push' && !triggers.onPush) {
+        console.error(`maestro-orchestrator: drop push-gate-off project=${payload.projectPath} mr=!${payload.mrIid} trigger=${payload.trigger}`)
         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))) {
+        console.error(`maestro-orchestrator: drop push-no-completed-history project=${payload.projectPath} mr=!${payload.mrIid} trigger=${payload.trigger}`)
         return { ok: true, failures: [], durationMs: Date.now() - t0 }
       }
       const { gitlabToken } = effective
       if (gitlabToken === undefined) {
         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}`)
+        console.error(`maestro-orchestrator: drop missing-token project=${payload.projectPath} mr=!${String(payload.mrIid)} trigger=${payload.trigger} — ${message}`)
         return { ok: false, failures: [message], durationMs: Date.now() - t0 }
       }
       const resolved = { ...effective, gitlabToken }
@@ -1307,7 +1343,7 @@ export function apply(ctx: Context, config: Config): void {
         : undefined
       await signals?.start()
       const postComment = async (body: string) => {
-        const response = await fetch(
+        const response = await GitlabClient.fetchWithTimeout(
           `${resolved.gitlabBaseUrl}/api/v4/projects/${payload.projectId}/merge_requests/${payload.mrIid}/notes`,
           {
             method: 'POST',
@@ -1318,7 +1354,7 @@ export function apply(ctx: Context, config: Config): void {
         if (!response.ok) throw new Error(`GitLab API error ${response.status}: ${await response.text()}`)
       }
       const replyToDiscussion = async (discussionId: string, body: string) => {
-        const response = await fetch(
+        const response = await GitlabClient.fetchWithTimeout(
           `${resolved.gitlabBaseUrl}/api/v4/projects/${payload.projectId}/merge_requests/${payload.mrIid}/discussions/${encodeURIComponent(discussionId)}/notes`,
           {
             method: 'POST',
@@ -1333,7 +1369,13 @@ export function apply(ctx: Context, config: Config): void {
           // 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)
+            const declined = await declineUnmappedDeepReview(payload, { postComment, replyToDiscussion, writeFailedReport, gitlabBaseUrl: resolved.gitlabBaseUrl } as unknown as ReviewCommentDeps)
+            if (!declined) {
+              console.error(`maestro-orchestrator: deduped duplicate in-flight review project=${payload.projectPath} mr=!${payload.mrIid} trigger=${payload.trigger}`)
+              await recordReviewFinish(historyId, { status: 'completed', summary: 'Duplicate in-flight review deduped — see the active run.' })
+              await signals?.finish('completed')
+              return { ok: true, summary: 'Duplicate in-flight review deduped — see the active run.', failures: [], durationMs: Date.now() - t0 }
+            }
             await recordReviewFinish(historyId, { status: 'completed', summary: 'Deep review declined (unmapped project)' })
             notifyTelegram('completed', 'Deep review declined (unmapped project)')
             await signals?.finish('completed')
@@ -1413,6 +1455,12 @@ export function apply(ctx: Context, config: Config): void {
               writeFailedReport,
               gitlabBaseUrl: resolved.gitlabBaseUrl,
             } as unknown as DiffOnlyReviewDeps)
+            if (diffBody === '') {
+              console.error(`maestro-orchestrator: deduped duplicate in-flight review project=${payload.projectPath} mr=!${payload.mrIid} trigger=${payload.trigger}`)
+              await recordReviewFinish(historyId, { status: 'completed', summary: 'Duplicate in-flight review deduped — see the active run.' })
+              await signals?.finish('completed')
+              return { ok: true, summary: 'Duplicate in-flight review deduped — see the active run.', failures: [], durationMs: Date.now() - t0 }
+            }
             const summary = summarize(diffBody)
             const branchNote = `fallback diff-only: branch ${payload.sourceBranch} not found on origin — ${summary ?? ''}`.trim()
             await recordReviewFinish(historyId, { status: 'completed', summary: branchNote })
@@ -1423,6 +1471,12 @@ export function apply(ctx: Context, config: Config): void {
           throw err
         }
         }
+        if (fullBody === '') {
+          console.error(`maestro-orchestrator: deduped duplicate in-flight review project=${payload.projectPath} mr=!${payload.mrIid} trigger=${payload.trigger}`)
+          await recordReviewFinish(historyId, { status: 'completed', summary: 'Duplicate in-flight review deduped — see the active run.' })
+          await signals?.finish('completed')
+          return { ok: true, summary: 'Duplicate in-flight review deduped — see the active run.', failures: [], durationMs: Date.now() - t0 }
+        }
         await recordReviewFinish(historyId, { status: 'completed', summary: summarize(fullBody) })
         notifyTelegram('completed', summarize(fullBody))
         await signals?.finish('completed')

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

@@ -64,15 +64,19 @@ export async function fetchMrSourceBranch(config: CiEnvConfig, fetcher: typeof f
   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 }> {
+/** MR detail pieces CI needs in one call: source branch (worktree) + head SHA (push-gate) + project path (comment header/link). */
+export async function fetchMrDetail(config: CiEnvConfig, fetcher: typeof fetch = fetch): Promise<{ sourceBranch: string; headSha: string; projectPath: 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 }
+  const body = await res.json() as { source_branch?: string; sha?: string; references?: { full?: 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 }
+  // references.full looks like "group/sub/project!123" — the real path feeds the
+  // comment header and View-MR link. Absent on old servers: fall back to project/<id>.
+  const full = body.references?.full
+  const projectPath = typeof full === 'string' && full.includes('!') ? full.slice(0, full.indexOf('!')) : `project/${config.sourceProjectId}`
+  return { sourceBranch: body.source_branch, headSha: body.sha, projectPath }
 }
 
 export async function runCiTrigger(
@@ -84,7 +88,7 @@ export async function runCiTrigger(
     history?: { lastCompletedReview(projectId: number, mrIid: number): Promise<{ headSha?: string } | undefined> }
   } = {},
 ): Promise<ReviewResult> {
-  const { sourceBranch, headSha } = await fetchMrDetail(config, deps.fetcher)
+  const { sourceBranch, headSha, projectPath } = 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
@@ -106,12 +110,12 @@ export async function runCiTrigger(
     } 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).
+    // The reviewer-ci profile's own projectMappings is always [], so the
+    // orchestrator's mapping lookup on projectPath never matches regardless
+    // of its exact value — but the real path feeds the comment header and
+    // View-MR link, so prefer it over the synthetic project/<id> fallback.
     const request: ReviewRequest = {
-      projectPath: `project/${config.sourceProjectId}`,
+      projectPath,
       projectId: config.sourceProjectId,
       mrIid: config.mrIid,
       sourceBranch,

package/src/host/providers/gitlab.ts

@@ -4,7 +4,7 @@ import z from '@deepseek-ai/schemastery'
 import { loadUserConfig } from '../config-store.js'
 import { secretsMatch } from '../secure-compare.js'
 import type { MrOpenedPayload, ReviewRequest as OrchestratorReviewRequest } from '../events.js'
-import { routeGitlabReviewRequest } from '../review-intake.js'
+import { describeDrop, routeGitlabReviewRequest } from '../review-intake.js'
 import type { ReviewProvider, ReviewRequest } from './interface.js'
 
 export const name = 'maestro-review-webhook'
@@ -127,10 +127,24 @@ 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 }
-        // 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)
+        const botUsername = userConfig.botUsername ?? config.botUsername ?? 'maestro'
+        if ((body.object_kind === 'merge_request' || body.object_kind === 'note') && !hasValidGitlabMrIdentity(body)) {
+          console.error(`maestro-review-webhook: drop invalid-identity object_kind=${(body as { object_kind?: unknown }).object_kind ?? 'unknown'}`)
+          res.writeHead(400).end(); return
+        }
+        // The orchestrator is the sole push gate (resolveReviewTriggers);
+        // intake always emits so per-project overrides keep working.
+        const request = routeGitlabReviewRequest(body, botUsername, { pushEnabled: true })
+        if (request === undefined) {
+          const reason = describeDrop(body, botUsername, { pushEnabled: true })
+          if (reason !== undefined) {
+            const project = (body as { project?: { path_with_namespace?: unknown } }).project
+            const source = (body as { object_attributes?: { iid?: unknown } }).object_attributes
+            console.error(`maestro-review-webhook: drop ${reason} project=${typeof project?.path_with_namespace === 'string' ? project.path_with_namespace : 'unknown'} mr=!${typeof source?.iid === 'number' ? source.iid : '?'}`)
+          }
+        } else {
+          ctx.emit('maestro/review-request', request)
+        }
         res.writeHead(200).end()
       })
     }

package/src/host/review-history.ts

@@ -64,10 +64,12 @@ function failStaleRunning(entries: ReviewHistoryEntry[]): boolean {
 
 /** Prepend a running entry; the oldest entries fall off past `HISTORY_CAP`. */
 export async function recordReviewStart(entry: Omit<ReviewHistoryEntry, 'status'>, dshHome?: string): Promise<void> {
-  const all = await readAll(dshHome)
-  if (failStaleRunning(all)) await writeAll(all, dshHome)
-  all.unshift({ ...entry, status: 'running' })
-  await writeAll(all.slice(0, HISTORY_CAP), dshHome)
+  return withHistoryLock(async () => {
+    const all = await readAll(dshHome)
+    if (failStaleRunning(all)) await writeAll(all, dshHome)
+    all.unshift({ ...entry, status: 'running' })
+    await writeAll(all.slice(0, HISTORY_CAP), dshHome)
+  })
 }
 
 /** Attach an outcome to the entry with this id; unknown ids are ignored. */
@@ -76,11 +78,13 @@ export async function recordReviewFinish(
   patch: { status: 'completed' | 'failed'; summary?: string; error?: string },
   dshHome?: string,
 ): Promise<void> {
-  const all = await readAll(dshHome)
-  const entry = all.find((candidate) => candidate.id === id)
-  if (entry === undefined) return
-  Object.assign(entry, patch, { finishedAt: Date.now() })
-  await writeAll(all, dshHome)
+  return withHistoryLock(async () => {
+    const all = await readAll(dshHome)
+    const entry = all.find((candidate) => candidate.id === id)
+    if (entry === undefined) return
+    Object.assign(entry, patch, { finishedAt: Date.now() })
+    await writeAll(all, dshHome)
+  })
 }
 
 /** Newest-first slice of the log. */
@@ -103,36 +107,62 @@ export async function lastCompletedReview(projectId: number, mrIid: number, dshH
 /**
  * Drop history entries and failed-report files older than `retentionDays`.
  * `0` disables pruning entirely. Maestro records only — DSH session
- * transcripts are never touched.
+ * transcripts are never touched. Entries still `running` are always kept:
+ * a prune must never delete a review that just started (see D3).
  */
 export async function pruneHistory(retentionDays: number, dshHome?: string): Promise<void> {
   if (!Number.isFinite(retentionDays) || retentionDays <= 0) return
-  const all = await readAll(dshHome)
-  failStaleRunning(all)
-  const cutoff = Date.now() - retentionDays * DAY_MS
-  const kept: ReviewHistoryEntry[] = []
-  for (const entry of all) {
-    if ((entry.finishedAt ?? entry.startedAt) < cutoff) continue
-    kept.push(entry)
-  }
-  await writeAll(kept, dshHome)
+  return withHistoryLock(async () => {
+    const all = await readAll(dshHome)
+    failStaleRunning(all)
+    const cutoff = Date.now() - retentionDays * DAY_MS
+    const kept: ReviewHistoryEntry[] = []
+    for (const entry of all) {
+      if (entry.status === 'running') {
+        kept.push(entry)
+        continue
+      }
+      if ((entry.finishedAt ?? entry.startedAt) < cutoff) continue
+      kept.push(entry)
+    }
+    await writeAll(kept, dshHome)
+  }).then(async () => {
+    const home = dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh')
+    const failedDir = join(home, 'maestro', 'failed-reports')
+    const cutoff = Date.now() - retentionDays * DAY_MS
+    let names: string[]
+    try {
+      names = await readdir(failedDir)
+    } catch {
+      return
+    }
+    await Promise.all(names.map(async (name) => {
+      // Failed reports are named `<mrIid>-<epoch-ms>.md`.
+      const match = /^-?\d+-(\d{13,})\.md$/.exec(name)
+      if (match === null) return
+      const stamp = Number(match[1])
+      if (!Number.isFinite(stamp) || stamp >= cutoff) return
+      await rm(join(failedDir, name), { force: true }).catch(() => {})
+    }))
+  })
+}
 
-  const home = dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh')
-  const failedDir = join(home, 'maestro', 'failed-reports')
-  let names: string[]
-  try {
-    names = await readdir(failedDir)
-  } catch {
-    return
-  }
-  await Promise.all(names.map(async (name) => {
-    // Failed reports are named `<mrIid>-<epoch-ms>.md`.
-    const match = /^-?\d+-(\d{13,})\.md$/.exec(name)
-    if (match === null) return
-    const stamp = Number(match[1])
-    if (!Number.isFinite(stamp) || stamp >= cutoff) return
-    await rm(join(failedDir, name), { force: true }).catch(() => {})
-  }))
+/**
+ * In-process promise-chain mutex serializing the read-modify-write cycles of
+ * `recordReviewStart` / `recordReviewFinish` / `pruneHistory`, so a
+ * fire-and-forget `void pruneHistory()` can no longer clobber an entry that
+ * started concurrently (last-writer-wins on a stale read). Two `dsh web`
+ * processes sharing one `DSH_HOME` is unsupported, so a cross-process file
+ * lock is deliberately out of scope.
+ */
+let historyMutex: Promise<void> = Promise.resolve()
+function withHistoryLock<T>(work: () => Promise<T>): Promise<T> {
+  const next = historyMutex.then(work, work)
+  historyMutex = next.then(
+    () => undefined,
+    () => undefined,
+  )
+  return next
 }
 
 const DAY_MS = 24 * 60 * 60_000

package/src/host/review-intake.ts

@@ -35,6 +35,19 @@ function isMentioned(text: string, botUsername: string): boolean {
   return new RegExp(`(^|[^A-Za-z0-9_.-])@${escaped}(?=$|[^A-Za-z0-9_.-])`, 'i').test(text)
 }
 
+/**
+ * Short head-sha hint for the in-flight key: prefers `last_commit.id`, falls
+ * back to `checkout_sha`. Returns `undefined` when the body carries no sha.
+ */
+function shortPushSha(attributes: JsonRecord): string | undefined {
+  const lastCommit = record(attributes.last_commit)
+  const raw = typeof lastCommit?.id === 'string' ? lastCommit.id
+    : typeof attributes.checkout_sha === 'string' ? attributes.checkout_sha
+    : undefined
+  if (raw === undefined || raw.trim() === '') return undefined
+  return raw.slice(0, 8)
+}
+
 function noteScope(attributes: JsonRecord): ReviewScope | undefined {
   const position = record(attributes.position)
   if (position === undefined) return { kind: 'mr' }
@@ -49,6 +62,28 @@ export interface RouteOptions {
   pushEnabled?: boolean
 }
 
+/** Actionable provider-layer drop reasons. Generic non-review GitLab noise
+ * (closes, label edits, ...) intentionally has no reason and stays silent. */
+export type DropReason = 'invalid-identity' | 'push-gate-off'
+
+/**
+ * Name why this webhook body will NOT route at the provider layer, or
+ * `undefined` when it routes (or is generic noise the provider ignores).
+ * Pure — the provider logs the returned reason with project/mr context.
+ */
+export function describeDrop(body: unknown, botUsername: string, options: RouteOptions = {}): DropReason | undefined {
+  const value = record(body)
+  if (value === undefined || botUsername.trim() === '') return 'invalid-identity'
+  const payload = mrPayload(value)
+  if (payload === undefined) return 'invalid-identity'
+  if (value.object_kind === 'merge_request') {
+    const attributes = record(value.object_attributes)
+    const hasNewCommits = typeof attributes?.oldrev === 'string' && attributes.oldrev !== ''
+    if (hasNewCommits && options.pushEnabled !== true) return 'push-gate-off'
+  }
+  return undefined
+}
+
 export function routeGitlabReviewRequest(body: unknown, botUsername: string, options: RouteOptions = {}): ReviewRequest | undefined {
   const value = record(body)
   if (value === undefined || botUsername.trim() === '') return undefined
@@ -65,7 +100,7 @@ export function routeGitlabReviewRequest(body: unknown, botUsername: string, opt
     if (options.pushEnabled === true) {
       const hasNewCommits = typeof attributes.oldrev === 'string' && attributes.oldrev !== ''
       if (hasNewCommits) {
-        return { ...payload, trigger: 'push', mode: 'quick', scope: { kind: 'mr' } }
+        return { ...payload, trigger: 'push', mode: 'quick', scope: { kind: 'mr' }, pushSha: shortPushSha(attributes) }
       }
     }
 

package/src/host/review-signals.ts

@@ -1,17 +1,19 @@
-import { gitlabAuthHeaders } from './gitlab-auth.js'
 /**
  * MR award-emoji acknowledgements: the MR shows "eyes" while a review runs and
  * a final marker when it completes or fails. Signalling is best-effort — any
  * GitLab error is swallowed so it can never fail the review itself.
  */
 
+import { gitlabAuthHeaders } from './gitlab-auth.js'
+import { fetchWithTimeout } from './gitlab-client.js'
+
 export interface ReviewSignals {
   start(): Promise<void>
   finish(outcome: 'completed' | 'failed'): Promise<void>
 }
 
 async function award(baseUrl: string, token: string, projectId: number, mrIid: number, name: string): Promise<void> {
-  await fetch(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji`, {
+  await fetchWithTimeout(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji`, {
     method: 'POST',
     headers: { ...gitlabAuthHeaders(token), 'Content-Type': 'application/json' },
     body: JSON.stringify({ name }),
@@ -20,14 +22,14 @@ async function award(baseUrl: string, token: string, projectId: number, mrIid: n
 
 /** Remove only this bot's stale running markers; other users' awards stay untouched. */
 async function unawardOwn(baseUrl: string, token: string, projectId: number, mrIid: number, botUsername: string): Promise<void> {
-  const response = await fetch(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji`, {
+  const response = await fetchWithTimeout(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji`, {
     headers: gitlabAuthHeaders(token),
   })
   if (!response.ok) return
   const awards = (await response.json()) as Array<{ id?: number; name?: string; user?: { username?: string } }>
   for (const awardItem of Array.isArray(awards) ? awards : []) {
     if (awardItem.name !== 'eyes' || awardItem.user?.username !== botUsername || typeof awardItem.id !== 'number') continue
-    await fetch(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji/${awardItem.id}`, {
+    await fetchWithTimeout(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji/${awardItem.id}`, {
       method: 'DELETE',
       headers: gitlabAuthHeaders(token),
     }).catch(() => {})