@desplega.ai/agent-swarm 1.111.0 → 1.113.0

package/src/be/rbac-audit.ts

@@ -0,0 +1,218 @@
+/**
+ * RBAC permission-audit batched writer + retention GC (DES-445, Phase 6).
+ *
+ * `enqueueAuditRow` is the concrete `AuditSink` wired into `can()` at server
+ * boot (src/http/index.ts, src/stdio.ts). Rows buffer in memory and flush in
+ * a single prepared-statement transaction every FLUSH_INTERVAL_MS (2s) or at
+ * FLUSH_MAX_ROWS (200), whichever comes first. Every path is try/caught — a
+ * failed flush logs a warning and DROPS the batch; auditing must never throw
+ * into the request path. Rows are structured ids/verbs only (no payloads, no
+ * secret-bearing content).
+ *
+ * Kill-switch: `RBAC_AUDIT_DISABLED=true` makes the sink a no-op (checked per
+ * call so tests and live config reloads can toggle it).
+ *
+ * Retention: `startAuditGc` (pattern: startMemoryGc in src/http/memory.ts)
+ * ticks daily and deletes rows older than RBAC_AUDIT_RETENTION_DAYS
+ * (default 30).
+ */
+import type { RbacCheck, RbacDecision } from "../rbac";
+import { getDb } from "./db";
+
+type AuditRow = {
+  principalType: "agent" | "user" | "operator";
+  principalId: string | null;
+  originatorUserId: string | null;
+  verb: string;
+  resourceType: string | null;
+  resourceId: string | null;
+  decision: "allow" | "deny";
+  reason: string | null;
+  source: "mcp" | "http";
+};
+
+const FLUSH_INTERVAL_MS = 2_000;
+const FLUSH_MAX_ROWS = 200;
+const AUDIT_GC_INTERVAL_MS = 24 * 60 * 60 * 1000; // daily
+const DEFAULT_RETENTION_DAYS = 30;
+
+let buffer: AuditRow[] = [];
+let flushTimer: ReturnType<typeof setInterval> | null = null;
+let auditGcTimer: ReturnType<typeof setInterval> | null = null;
+let thresholdFlushScheduled = false;
+
+function isAuditDisabled(): boolean {
+  return process.env.RBAC_AUDIT_DISABLED === "true";
+}
+
+function principalIdOf(principal: RbacCheck["principal"]): string | null {
+  switch (principal.kind) {
+    case "agent":
+      return principal.agentId;
+    case "user":
+      return principal.userId;
+    case "operator":
+      return null;
+  }
+}
+
+function resourceIdOf(resource: RbacCheck["resource"]): string | null {
+  if (!resource) return null;
+  switch (resource.kind) {
+    case "task":
+      return resource.taskId;
+    case "agent":
+      return resource.agentId;
+    case "kv-namespace":
+      return resource.namespace;
+    case "owned":
+      return resource.ownerAgentId ?? null;
+    case "none":
+      return null;
+  }
+}
+
+function toRow(check: RbacCheck, decision: RbacDecision): AuditRow {
+  return {
+    principalType: check.principal.kind,
+    principalId: principalIdOf(check.principal),
+    // Reserved: slice-1 RbacCheck carries no originating-user field yet.
+    originatorUserId: null,
+    verb: check.verb,
+    resourceType: check.resource?.kind ?? null,
+    resourceId: resourceIdOf(check.resource),
+    decision: decision.allow ? "allow" : "deny",
+    reason: decision.allow ? null : decision.reason,
+    source: check.source,
+  };
+}
+
+/**
+ * The concrete AuditSink for `can()`. Never throws — `can()` already swallows
+ * sink exceptions, but the audit path defends independently.
+ */
+export function enqueueAuditRow(check: RbacCheck, decision: RbacDecision): void {
+  if (isAuditDisabled()) return;
+  try {
+    buffer.push(toRow(check, decision));
+    // The threshold flush is deferred to a zero-delay timeout so the can()
+    // call that happens to be the 200th never pays for the SQLite transaction
+    // itself — audit stays fire-and-forget on the request path.
+    if (buffer.length >= FLUSH_MAX_ROWS && !thresholdFlushScheduled) {
+      thresholdFlushScheduled = true;
+      const t = setTimeout(() => {
+        thresholdFlushScheduled = false;
+        flushAuditBuffer();
+      }, 0);
+      if (typeof t.unref === "function") t.unref();
+    }
+  } catch (err) {
+    console.warn("[rbac-audit] enqueue failed, dropping row:", (err as Error).message);
+  }
+}
+
+/**
+ * Drain the buffer into permission_audit in one transaction. Called by the
+ * flush interval, the 200-row threshold, and shutdown. A failed flush logs a
+ * warning and drops the batch — never throws.
+ */
+export function flushAuditBuffer(): void {
+  if (buffer.length === 0) return;
+  const rows = buffer;
+  buffer = [];
+  try {
+    const db = getDb();
+    const stmt = db.prepare(
+      `INSERT INTO permission_audit
+         (principalType, principalId, originatorUserId, verb, resourceType, resourceId, decision, reason, source)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    const insertAll = db.transaction((batch: AuditRow[]) => {
+      for (const r of batch) {
+        stmt.run(
+          r.principalType,
+          r.principalId,
+          r.originatorUserId,
+          r.verb,
+          r.resourceType,
+          r.resourceId,
+          r.decision,
+          r.reason,
+          r.source,
+        );
+      }
+    });
+    insertAll(rows);
+  } catch (err) {
+    console.warn(
+      `[rbac-audit] flush failed, dropping ${rows.length} row(s):`,
+      (err as Error).message,
+    );
+  }
+}
+
+/**
+ * Test hook, not a production knob: rbac-lifecycle-e2e.test.ts sets a huge
+ * interval so the SIGTERM-drain assertion can prove rows were persisted by
+ * the shutdown drain rather than a racing timer tick.
+ */
+function flushIntervalMs(): number {
+  const v = Number(process.env.RBAC_AUDIT_FLUSH_MS);
+  return Number.isFinite(v) && v > 0 ? v : FLUSH_INTERVAL_MS;
+}
+
+/** Start the periodic flush (2s tick). Idempotent. */
+export function startAuditWriter(intervalMs = flushIntervalMs()): void {
+  if (flushTimer) return;
+  flushTimer = setInterval(() => flushAuditBuffer(), intervalMs);
+  if (typeof flushTimer?.unref === "function") flushTimer.unref();
+}
+
+/** Stop the periodic flush. Does NOT flush — shutdown calls flushAuditBuffer(). */
+export function stopAuditWriter(): void {
+  if (flushTimer) {
+    clearInterval(flushTimer);
+    flushTimer = null;
+  }
+}
+
+/** Delete audit rows older than the retention window. Returns rows deleted. */
+export function purgeExpiredAuditRows(): number {
+  try {
+    const days = Number(process.env.RBAC_AUDIT_RETENTION_DAYS) || DEFAULT_RETENTION_DAYS;
+    // ts is CURRENT_TIMESTAMP format ("YYYY-MM-DD HH:MM:SS"); compute the
+    // cutoff in SQLite so the string formats always match.
+    const result = getDb()
+      .prepare("DELETE FROM permission_audit WHERE ts < datetime('now', ?)")
+      .run(`-${days} days`);
+    return result.changes;
+  } catch (err) {
+    console.warn("[rbac-audit] retention purge failed:", (err as Error).message);
+    return 0;
+  }
+}
+
+/** Start the retention GC (daily tick, immediate first run). Idempotent. */
+export function startAuditGc(intervalMs = AUDIT_GC_INTERVAL_MS): void {
+  if (auditGcTimer) return;
+
+  const purged = purgeExpiredAuditRows();
+  if (purged > 0) {
+    console.log(`[rbac-audit] Initial retention purge removed ${purged} audit row(s)`);
+  }
+
+  auditGcTimer = setInterval(() => {
+    const n = purgeExpiredAuditRows();
+    if (n > 0) {
+      console.log(`[rbac-audit] Retention purge removed ${n} audit row(s)`);
+    }
+  }, intervalMs);
+  if (typeof auditGcTimer?.unref === "function") auditGcTimer.unref();
+}
+
+export function stopAuditGc(): void {
+  if (auditGcTimer) {
+    clearInterval(auditGcTimer);
+    auditGcTimer = null;
+  }
+}

package/src/be/scripts/typecheck.ts

@@ -137,6 +137,8 @@ export interface SwarmSdk {
   slack_startThread(args: { channelId: string; message: string }): Promise<unknown>;
   slack_uploadFile(args: Record<string, unknown>): Promise<unknown>;
   slack_downloadFile(args: { url: string }): Promise<unknown>;
+  slack_delete(args: { channelId: string; messageTs: string }): Promise<unknown>;
+  slack_update(args: { channelId: string; messageTs: string; message: string }): Promise<unknown>;
 
   // --- write: messaging (internal) ---
   message_post(args: { channel?: string; content: string; to?: string }): Promise<unknown>;

package/src/commands/runner.ts

@@ -196,9 +196,111 @@ async function listSwarmAutostashes(clonePath: string, role: string): Promise<Sw
   }
 }
 
+/**
+ * Continuation task types that must NEVER take the destructive hard-reset path,
+ * even though they are not `taskType === "resume"`. Each of these ingress paths
+ * creates a NEW task that CONTINUES/cooperates with existing work — often on the
+ * same worker/reused clone — rather than starting genuinely fresh coding work:
+ *  - "follow-up" / "reroute-decision": lead-owned continuations created by
+ *    src/tasks/worker-follow-up.ts after a task completes/fails or needs
+ *    re-delegation; they inherit the parent's vcsRepo/branch context via
+ *    createTaskExtended's parentTaskId inheritance (src/be/db.ts).
+ *  - "agentmail-reply": AgentMail follow-up on an EXISTING thread
+ *    (src/agentmail/handlers.ts) — always carries `parentTaskId` pointing at
+ *    the task it's continuing (as opposed to "agentmail-message", which fires
+ *    only when no existing task was found for the thread).
+ *  - "github-comment" / "github-review" / "gitlab-comment" / "gitlab-ci":
+ *    tracker feedback on an ALREADY-OPEN PR/MR (review comments, review
+ *    verdicts, CI failures) — the point is to keep working on the existing
+ *    feature branch, not reset back to the default branch.
+ */
+const CONTINUATION_TASK_TYPES = new Set([
+  "resume",
+  "follow-up",
+  "reroute-decision",
+  "agentmail-reply",
+  "github-comment",
+  "github-review",
+  "gitlab-comment",
+  "gitlab-ci",
+]);
+
+/**
+ * Task statuses under which a task may have already mutated the shared clone
+ * (checked out a feature branch, left uncommitted/unpushed work) — or could
+ * still be doing so concurrently, e.g. with `maxTasks > 1` on the same worker.
+ * Mirrors the ACTIVE_TASK_STATUSES / getInProgressTasksByContextKey status
+ * sets already used server-side (src/agentmail/handlers.ts, src/be/db.ts) for
+ * the same "is this task still doing live work" question.
+ */
+const ACTIVE_PARENT_STATUSES = new Set<string>(["pending", "in_progress", "offered", "paused"]);
+
+/**
+ * A task is a "first kickoff" (safe to hard-reset the base branch) only when it
+ * is BOTH (a) not an explicit continuation task-type and (b) not parent-linked
+ * to a still-active task.
+ *
+ * `parentTaskId` alone is NOT a resume signal — send-task/trackers set it on
+ * ~every dispatched child task (verified 395/395 real coding tasks carried one;
+ * 0 were typed "resume"), so gating on its mere presence made the reset a no-op
+ * in production (see git history on this function). But the *opposite*
+ * over-correction — treating every non-"resume" task as a safe root kickoff —
+ * is also wrong: several ingress paths create parent-linked NON-resume tasks
+ * specifically to CONTINUE existing work, often on the same worker/reused
+ * clone:
+ *  - Slack follow-ups (src/slack/handlers.ts) wire `parentTaskId:
+ *    latestTask?.id` with NO distinguishing taskType at all.
+ *  - Sibling-awareness (src/tasks/sibling-awareness.ts, applied to every
+ *    ingress via createTaskWithSiblingAwareness) wires `parentTaskId` to an
+ *    in-progress same-agent sibling for session continuity — again with no
+ *    reserved taskType.
+ *  - AgentMail replies, tracker comments/reviews/CI events — see
+ *    CONTINUATION_TASK_TYPES.
+ * Since the first two carry no reserved taskType, a taskType denylist alone
+ * cannot catch them — we ALSO check whether `parentTaskId` currently points at
+ * a still-active task (ACTIVE_PARENT_STATUSES). If so, that parent/sibling may
+ * hold a checked-out feature branch or unpushed/uncommitted work in the SAME
+ * shared clone (especially with `maxTasks > 1`), so a hard reset there would
+ * destroy it — take the non-destructive merge path instead.
+ *
+ * `fetchParentTaskStatus` is injected so this stays a pure, unit-testable
+ * function; the real call site fetches `GET /api/tasks/{id}` (same pattern as
+ * fetchProviderSessionInfo below).
+ */
+export async function isFirstKickoffTask(
+  task?: { taskType?: string; parentTaskId?: string } | null,
+  fetchParentTaskStatus?: (parentTaskId: string) => Promise<string | null | undefined>,
+): Promise<boolean> {
+  if (task?.taskType && CONTINUATION_TASK_TYPES.has(task.taskType)) return false;
+  if (task?.parentTaskId && fetchParentTaskStatus) {
+    const parentStatus = await fetchParentTaskStatus(task.parentTaskId);
+    if (parentStatus && ACTIVE_PARENT_STATUSES.has(parentStatus)) return false;
+  }
+  return true;
+}
+
+/** Fetch a task's current status by id. Returns null on any failure (not-found, network, etc). */
+async function fetchTaskStatus(
+  apiUrl: string,
+  apiKey: string,
+  taskId: string,
+): Promise<string | null> {
+  const headers: Record<string, string> = {};
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  try {
+    const response = await fetch(`${apiUrl}/api/tasks/${taskId}`, { headers });
+    if (!response.ok) return null;
+    const data = (await response.json()) as { status?: string };
+    return data.status ?? null;
+  } catch {
+    return null;
+  }
+}
+
 async function refreshExistingRepoForTask(
   repoConfig: { name: string; clonePath: string; defaultBranch: string },
   role: string,
+  isFirstKickoff: boolean,
 ): Promise<string | null> {
   const { name, clonePath, defaultBranch } = repoConfig;
   const statusResult =
@@ -219,13 +321,36 @@ async function refreshExistingRepoForTask(
     }
   }
 
+  const fetchSpec = `${defaultBranch}:refs/remotes/origin/${defaultBranch}`;
+  const remoteRef = `refs/remotes/origin/${defaultBranch}`;
+
   try {
-    console.log(`[${role}] Refreshing ${name} from origin/${defaultBranch}...`);
-    const fetchSpec = `${defaultBranch}:refs/remotes/origin/${defaultBranch}`;
-    const remoteRef = `refs/remotes/origin/${defaultBranch}`;
     await Bun.$`env -u GIT_DIR -u GIT_WORK_TREE -u GIT_INDEX_FILE -u GIT_PREFIX git -C ${clonePath} fetch origin ${fetchSpec}`.quiet();
-    await Bun.$`env -u GIT_DIR -u GIT_WORK_TREE -u GIT_INDEX_FILE -u GIT_PREFIX git -C ${clonePath} merge --no-edit --no-stat ${remoteRef}`.quiet();
-    console.log(`[${role}] Refreshed ${name}`);
+
+    // First-kickoff guarantee (see call sites): the clone is REUSED task-to-task,
+    // so a leftover feature branch from a prior task can still be checked out here.
+    // On a genuine first kickoff (no parentTaskId / not a resume) we force the base
+    // branch back to a clean, current state before the caller creates a work branch
+    // off it — otherwise a diverged leftover branch would abort the merge below and
+    // leave the repo stale (only a warning was emitted). Resumes and follow-up/child
+    // tasks (which may legitimately still have that feature branch checked out with
+    // in-progress work) must NEVER take this path — merge is the safe default there.
+    if (isFirstKickoff) {
+      console.log(`[${role}] First kickoff for ${name} — resetting to ${remoteRef}...`);
+      try {
+        await Bun.$`env -u GIT_DIR -u GIT_WORK_TREE -u GIT_INDEX_FILE -u GIT_PREFIX git -C ${clonePath} checkout ${defaultBranch}`.quiet();
+      } catch {
+        // Local branch may be missing (e.g. deleted by a prior task) — recreate it
+        // tracking the remote instead of failing the whole refresh.
+        await Bun.$`env -u GIT_DIR -u GIT_WORK_TREE -u GIT_INDEX_FILE -u GIT_PREFIX git -C ${clonePath} checkout -B ${defaultBranch} ${remoteRef}`.quiet();
+      }
+      await Bun.$`env -u GIT_DIR -u GIT_WORK_TREE -u GIT_INDEX_FILE -u GIT_PREFIX git -C ${clonePath} reset --hard ${remoteRef}`.quiet();
+      console.log(`[${role}] Reset ${name} to ${remoteRef}`);
+    } else {
+      console.log(`[${role}] Refreshing ${name} from ${remoteRef}...`);
+      await Bun.$`env -u GIT_DIR -u GIT_WORK_TREE -u GIT_INDEX_FILE -u GIT_PREFIX git -C ${clonePath} merge --no-edit --no-stat ${remoteRef}`.quiet();
+      console.log(`[${role}] Refreshed ${name}`);
+    }
     return null;
   } catch (err) {
     const errorMsg = scrubSecrets((err as Error).message);
@@ -278,6 +403,13 @@ export async function ensureRepoForTask(
     hooks?: { enabled: boolean } | null;
   },
   role: string,
+  /**
+   * True only for a genuine first kickoff (a brand-new task, not a resume and
+   * not a follow-up/child task continuing prior work). Defaults to false —
+   * when in doubt, do NOT force-reset the base branch, since the clone is
+   * reused task-to-task and may hold another task's in-progress branch.
+   */
+  isFirstKickoff = false,
 ): Promise<{
   clonePath: string;
   claudeMd: string | null;
@@ -308,7 +440,11 @@ export async function ensureRepoForTask(
       console.log(`[${role}] Cloned ${name}`);
     } else {
       console.log(`[${role}] Repo ${name} already cloned at ${clonePath}`);
-      warning = await refreshExistingRepoForTask({ name, clonePath, defaultBranch }, role);
+      warning = await refreshExistingRepoForTask(
+        { name, clonePath, defaultBranch },
+        role,
+        isFirstKickoff,
+      );
     }
 
     await installRepoHooksForTask(repoConfig, role);
@@ -4794,7 +4930,9 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
             clonePath: `/workspace/personal/repos/${task.vcsRepo.split("/").pop() || task.vcsRepo}`,
             defaultBranch: "main",
           };
-          const repoContext = await ensureRepoForTask(effectiveConfig, role);
+          // This is the paused-task-resume-after-restart path — never a first
+          // kickoff, so never force-reset the base branch here.
+          const repoContext = await ensureRepoForTask(effectiveConfig, role, false);
           if (repoContext?.clonePath) {
             resumeCwd = repoContext.clonePath;
           }
@@ -5187,7 +5325,15 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
             clonePath: `/workspace/personal/repos/${taskVcsRepo.split("/").pop() || taskVcsRepo}`,
             defaultBranch: "main",
           };
-          const repoResult = await ensureRepoForTask(effectiveConfig, role);
+          // First kickoff = a genuinely new root task: not a continuation
+          // task-type, and not parent-linked to a still-active task (Slack
+          // follow-ups / sibling-awareness wire parentTaskId with no
+          // reserved taskType). See isFirstKickoffTask() for the full
+          // reasoning and CONTINUATION_TASK_TYPES for the denylist.
+          const isFirstKickoff = await isFirstKickoffTask(taskObj, (parentTaskId) =>
+            fetchTaskStatus(apiUrl, apiKey, parentTaskId),
+          );
+          const repoResult = await ensureRepoForTask(effectiveConfig, role, isFirstKickoff);
           currentRepoContext = {
             ...repoResult,
             guidelines: repoConfig?.guidelines ?? null,

package/src/github/handlers.ts

@@ -944,6 +944,12 @@ interface ReviewInlineComment {
   body: string;
   html_url: string;
   diff_hunk: string;
+  pull_request_review_id?: number | null;
+}
+
+interface FetchReviewCommentsResult {
+  comments: ReviewInlineComment[];
+  degraded: boolean;
 }
 
 function parseNextPageLink(linkHeader: string | null): string | null {
@@ -952,30 +958,38 @@ function parseNextPageLink(linkHeader: string | null): string | null {
   return match ? (match[1] ?? null) : null;
 }
 
-async function fetchReviewComments(
-  repo: string,
-  prNumber: number,
-  reviewId: number,
-  installationId: number,
-): Promise<ReviewInlineComment[]> {
-  const token = await getInstallationToken(installationId);
-  if (!token) {
-    return [];
-  }
-  const headers = {
+const REVIEW_COMMENTS_EMPTY_RETRY_DELAYS_MS = [1_500, 3_000, 3_000];
+const defaultReviewCommentsRetryDelay = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+let reviewCommentsRetryDelay: (ms: number) => Promise<void> | void =
+  defaultReviewCommentsRetryDelay;
+
+export function setReviewCommentsRetryDelayForTests(
+  delay?: (ms: number) => Promise<void> | void,
+): void {
+  reviewCommentsRetryDelay = delay ?? defaultReviewCommentsRetryDelay;
+}
+
+function buildReviewCommentsHeaders(token: string): Record<string, string> {
+  return {
     Accept: "application/vnd.github+json",
     Authorization: `Bearer ${token}`,
     "X-GitHub-Api-Version": "2022-11-28",
   };
+}
+
+async function fetchPaginatedReviewComments(
+  initialUrl: string,
+  headers: Record<string, string>,
+): Promise<FetchReviewCommentsResult> {
   const allComments: ReviewInlineComment[] = [];
-  let url: string | null =
-    `https://api.github.com/repos/${repo}/pulls/${prNumber}/reviews/${reviewId}/comments?per_page=100`;
+  let url: string | null = initialUrl;
   try {
     while (url) {
       const response = await fetch(url, { headers });
       if (!response.ok) {
         console.error(`[GitHub] Failed to fetch review inline comments: ${response.status}`);
-        return allComments;
+        return { comments: allComments, degraded: true };
       }
       const page = (await response.json()) as ReviewInlineComment[];
       if (Array.isArray(page)) {
@@ -983,11 +997,92 @@ async function fetchReviewComments(
       }
       url = parseNextPageLink(response.headers.get("link"));
     }
-    return allComments;
+    return { comments: allComments, degraded: false };
   } catch (error) {
     console.error("[GitHub] Error fetching review inline comments:", error);
-    return allComments;
+    return { comments: allComments, degraded: true };
+  }
+}
+
+async function fetchReviewScopedComments(
+  repo: string,
+  prNumber: number,
+  reviewId: number,
+  headers: Record<string, string>,
+): Promise<FetchReviewCommentsResult> {
+  const url = `https://api.github.com/repos/${repo}/pulls/${prNumber}/reviews/${reviewId}/comments?per_page=100`;
+
+  let result = await fetchPaginatedReviewComments(url, headers);
+  if (result.degraded || result.comments.length > 0) {
+    return result;
+  }
+
+  for (const delayMs of REVIEW_COMMENTS_EMPTY_RETRY_DELAYS_MS) {
+    await reviewCommentsRetryDelay(delayMs);
+    result = await fetchPaginatedReviewComments(url, headers);
+    if (result.degraded || result.comments.length > 0) {
+      return result;
+    }
   }
+
+  return result;
+}
+
+async function fetchPrLevelReviewComments(
+  repo: string,
+  prNumber: number,
+  reviewId: number,
+  headers: Record<string, string>,
+): Promise<FetchReviewCommentsResult> {
+  const url = `https://api.github.com/repos/${repo}/pulls/${prNumber}/comments?per_page=100`;
+  const result = await fetchPaginatedReviewComments(url, headers);
+  return {
+    comments: result.comments.filter((comment) => comment.pull_request_review_id === reviewId),
+    degraded: result.degraded,
+  };
+}
+
+function dedupeReviewComments(comments: ReviewInlineComment[]): ReviewInlineComment[] {
+  const byId = new Map<number, ReviewInlineComment>();
+  for (const comment of comments) {
+    if (!byId.has(comment.id)) {
+      byId.set(comment.id, comment);
+    }
+  }
+  return [...byId.values()];
+}
+
+async function fetchReviewComments(
+  repo: string,
+  prNumber: number,
+  reviewId: number,
+  installationId: number,
+): Promise<FetchReviewCommentsResult> {
+  const token = await getInstallationToken(installationId);
+  if (!token) {
+    return { comments: [], degraded: true };
+  }
+
+  const headers = buildReviewCommentsHeaders(token);
+  const scopedResult = await fetchReviewScopedComments(repo, prNumber, reviewId, headers);
+  if (!scopedResult.degraded && scopedResult.comments.length > 0) {
+    return scopedResult;
+  }
+
+  const fallbackResult = await fetchPrLevelReviewComments(repo, prNumber, reviewId, headers);
+  const mergedComments = dedupeReviewComments([
+    ...scopedResult.comments,
+    ...fallbackResult.comments,
+  ]);
+
+  if (fallbackResult.comments.length > 0) {
+    return { comments: mergedComments, degraded: false };
+  }
+
+  return {
+    comments: mergedComments,
+    degraded: scopedResult.degraded || fallbackResult.degraded,
+  };
 }
 
 function buildInlineCommentsSection(comments: ReviewInlineComment[]): string {
@@ -1000,6 +1095,13 @@ function buildInlineCommentsSection(comments: ReviewInlineComment[]): string {
   return `\n\n## Inline review comments (${comments.length})\n\n${items.join("\n\n")}`;
 }
 
+function buildInlineCommentsDegradedSection(repo: string, prNumber: number): string {
+  return `\n\n## ⚠️ Inline comments could NOT be auto-fetched
+The automatic inline-comment fetch failed or was unverifiable while the reviewer submitted this review. Inline comments ARE the change requests. BEFORE scoping or dispatching this task you MUST fetch them yourself:
+\`gh api "repos/${repo}/pulls/${prNumber}/comments?per_page=100" --jq '.[] | {id,path,line,body}'\`
+Reply to and resolve EVERY unresolved inline thread. Do NOT dispatch off the review body alone.`;
+}
+
 /**
  * Handle pull_request_review events (submitted, edited, dismissed)
  *
@@ -1033,15 +1135,13 @@ export async function handlePullRequestReview(
     return { created: false };
   }
 
-  // Fetch inline comments now so we can decide whether to skip and include them in the task.
-  // Returns [] when no installation credentials are available (graceful degradation).
-  const inlineComments = installation?.id
+  const { comments: inlineComments, degraded } = installation?.id
     ? await fetchReviewComments(repository.full_name, pr.number, review.id, installation.id)
-    : [];
+    : { comments: [], degraded: true };
 
   // Skip "commented" reviews only when there is neither an overall body nor any inline
   // comments — a body-less review with inline comments carries real reviewer feedback.
-  if (review.state === "commented" && !review.body && inlineComments.length === 0) {
+  if (review.state === "commented" && !review.body && inlineComments.length === 0 && !degraded) {
     return { created: false };
   }
 
@@ -1062,7 +1162,9 @@ export async function handlePullRequestReview(
 
   // Build task description
   const reviewBodySection = review.body ? `\n\nReview Comment:\n${review.body}` : "";
-  const inlineCommentsSection = buildInlineCommentsSection(inlineComments);
+  const inlineCommentsSection =
+    buildInlineCommentsSection(inlineComments) +
+    (degraded ? buildInlineCommentsDegradedSection(repository.full_name, pr.number) : "");
   const relatedTaskSection = existingTask
     ? `Related task: ${existingTask.id}\n🔀 Consider routing to the same agent working on the related task.\n`
     : "";
@@ -1074,9 +1176,10 @@ export async function handlePullRequestReview(
       : review.state === "changes_requested"
         ? "💡 Suggested: Address the requested changes and update the PR"
         : "💡 Suggested: Review the feedback and respond if needed";
-  const reviewSuggestions = hasInlineComments
-    ? `${baseReviewSuggestion}\n💬 Address EVERY inline comment. After pushing fixes, reply to and resolve each inline review thread on GitHub so the reviewer sees visible confirmation.`
-    : baseReviewSuggestion;
+  const reviewSuggestions =
+    hasInlineComments || degraded
+      ? `${baseReviewSuggestion}\n💬 Address EVERY inline comment. After pushing fixes, reply to and resolve each inline review thread on GitHub so the reviewer sees visible confirmation.`
+      : baseReviewSuggestion;
 
   const result = resolveTemplate(
     "github.pull_request.review_submitted",