glab-agent 0.2.9 → 0.2.11

package/README.md

@@ -153,6 +153,16 @@ No extra dashboards needed. glab-agent maps to GitLab's native features:
 - **Metrics** — Append-only JSONL per agent (`.glab-agent/metrics/`)
 - **Heartbeat** — Cycle count and last error in `.glab-agent/heartbeat/`
 
+## Documentation
+
+Development documentation lives in [`docs/`](docs/index.md):
+
+- **[Design Principles](docs/design-principles.md)** — P1-P17, architecture decision criteria
+- **[Test Strategy](docs/test-strategy.md)** — coverage policy, key modules, known gaps
+- **[Harness Engineering](docs/harness-engineering.md)** — human + AI collaboration methodology
+
+Run `glab-agent doctor` for environment diagnostics.
+
 ## Requirements
 
 - Node.js >= 20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glab-agent",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "type": "module",
   "description": "Multi-agent GitLab To-Do watcher with YAML-defined agents, skills, and GitLab registry.",
   "license": "MIT",
@@ -34,7 +34,9 @@
     "prepare": "git config core.hooksPath scripts/hooks",
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "agent": "tsx src/local-agent/cli.ts",
+    "check:deliver": "zsh scripts/delivery-check.sh",
     "smoke-test": "zsh scripts/smoke-test.sh",
     "smoke-test:full": "zsh scripts/smoke-test.sh --wait-finish",
     "docs-lint": "zsh scripts/docs-lint.sh",

package/src/local-agent/agent-runner.ts

@@ -22,6 +22,8 @@ export interface AgentRunResult {
 export interface AgentRunContext {
   todoId?: number;
   signal?: AbortSignal;
+  /** Hint when issue labels don't match trigger config. Passed to agent prompt. */
+  labelMismatchHint?: string;
 }
 
 export interface SpawnedRunResult {
@@ -116,6 +118,8 @@ export interface AgentPromptContext {
   append?: string;
   templatePath?: string;
   labels?: AgentLabelConfig;
+  /** Hint when issue labels don't match trigger config. Agent decides how to respond. */
+  labelMismatchHint?: string;
 }
 
 export interface ContextualPromptContext {
@@ -227,6 +231,7 @@ export function buildBasePrompt(ctx: AgentPromptContext): string {
     "## 当前环境",
     `- 分支: ${ctx.branch}`,
     "- 工作目录: 项目的独立工作副本",
+    ctx.labelMismatchHint ? `\n## 注意\n${ctx.labelMismatchHint}` : "",
     "",
     "## 最终输出",
     "标准输出不超过 5 行的简短总结（不是 GitLab 评论）。"

package/src/local-agent/claude-runner.ts

@@ -75,6 +75,7 @@ export class ClaudeRunner implements AgentRunner {
       preamble: this.agentDefinition?.prompt.preamble,
       append: this.agentDefinition?.prompt.append,
       labels: this.agentDefinition?.labels,
+      labelMismatchHint: context?.labelMismatchHint,
       // skills injected via .claude/skills/*.md files, not in prompt
     });
     const claudeCommand = resolveClaudeCommand(this.env);
@@ -158,6 +159,7 @@ export class ClaudeRunner implements AgentRunner {
       preamble: this.agentDefinition?.prompt.preamble,
       append: this.agentDefinition?.prompt.append,
       labels: this.agentDefinition?.labels,
+      labelMismatchHint: context?.labelMismatchHint,
     });
     const claudeCommand = resolveClaudeCommand(this.env);
 

package/src/local-agent/cli.ts

@@ -97,6 +97,7 @@ Commands:
   watch <name>           Watch agent status in real-time (refreshes every 5s)
   history <name>         Show agent execution history (--last N, default 20)
   report <name>          Show execution report (--since <N>d, default 7d) [--publish]
+  dashboard              Multi-agent overview (status + recent runs + alerts)
   sweep <name|--all>     Move merged In Review issues to Done
   gc <name|--all>        Remove worktrees for closed/merged issues
   install <name|--all>   Generate launchd plist for agent(s)
@@ -2214,6 +2215,113 @@ async function cmdWikiSetup(): Promise<void> {
   console.log(`  ${wikiUrl(remote.host, remote.projectPath, "home")}`);
 }
 
+// ── Dashboard command ─────────────────────────────────────────────────────
+
+async function cmdDashboard(): Promise<void> {
+  const agents = await discoverAgents(AGENTS_DIR).catch(() => []);
+  if (agents.length === 0) {
+    console.log("No agents found. Run 'glab-agent init <name>' first.");
+    return;
+  }
+
+  // ── Agent Status Table ──
+  console.log("AGENTS");
+  console.log("-".repeat(80));
+  const nameW = 20;
+  const statusW = 10;
+  const taskW = 35;
+  const lastW = 15;
+  console.log(
+    `${"Name".padEnd(nameW)}${"Status".padEnd(statusW)}${"Current Task".padEnd(taskW)}${"Last Run".padEnd(lastW)}`
+  );
+  console.log("-".repeat(80));
+
+  const alerts: string[] = [];
+
+  for (const agent of agents) {
+    const status = await getAgentStatus(PROJECT_DIR, agent.name);
+    const statePath = agentStatePath(PROJECT_DIR, agent.name);
+    const store = new FileStateStore(statePath);
+    const state = await store.load();
+
+    // Status
+    const statusStr = status.alive ? "busy" : "idle";
+
+    // Current task
+    let taskStr = "\u2014";
+    if (state.activeRun) {
+      taskStr = `#${state.activeRun.issueIid}`;
+    }
+
+    // Last run info
+    const history = state.runHistory ?? [];
+    let lastRunStr = "\u2014";
+    if (history.length > 0) {
+      const last = history[history.length - 1];
+      const ago = Math.round((Date.now() - new Date(last.finishedAt).getTime()) / 60000);
+      if (ago < 60) lastRunStr = `${ago}min ago`;
+      else if (ago < 1440) lastRunStr = `${Math.round(ago / 60)}hr ago`;
+      else lastRunStr = `${Math.round(ago / 1440)}d ago`;
+    }
+
+    console.log(
+      `${agent.name.padEnd(nameW)}${statusStr.padEnd(statusW)}${taskStr.slice(0, taskW - 1).padEnd(taskW)}${lastRunStr.padEnd(lastW)}`
+    );
+
+    // Collect alerts
+    if (history.length > 0) {
+      const last = history[history.length - 1];
+      if (last.status === "failed") {
+        alerts.push(`${agent.name} #${last.issueIid} failed — check: pnpm agent logs ${agent.name}`);
+      }
+    }
+
+    // Check heartbeat staleness
+    const hbPath = agentHeartbeatPath(PROJECT_DIR, agent.name);
+    const hb = await readHeartbeat(hbPath);
+    if (hb && isHeartbeatStale(hb, 300)) {
+      alerts.push(`${agent.name} heartbeat stale (>5min) — may need restart`);
+    }
+  }
+
+  // ── Recent Runs ──
+  console.log("\nRECENT (last 10 across all agents)");
+  console.log("-".repeat(80));
+
+  const allRuns: Array<{ agentName: string; entry: RunHistoryEntry }> = [];
+  for (const agent of agents) {
+    const statePath = agentStatePath(PROJECT_DIR, agent.name);
+    const store = new FileStateStore(statePath);
+    const state = await store.load();
+    for (const entry of state.runHistory ?? []) {
+      allRuns.push({ agentName: agent.name, entry });
+    }
+  }
+
+  allRuns.sort((a, b) => new Date(b.entry.finishedAt).getTime() - new Date(a.entry.finishedAt).getTime());
+
+  const recentRuns = allRuns.slice(0, 10);
+  if (recentRuns.length === 0) {
+    console.log("  No execution history yet.");
+  } else {
+    for (const { agentName, entry } of recentRuns) {
+      const status = entry.status === "completed" ? "done" : entry.status;
+      const duration = formatDuration(entry.startedAt, entry.finishedAt);
+      const title = (entry.issueTitle ?? "").slice(0, 30);
+      console.log(`  ${agentName.padEnd(16)} #${String(entry.issueIid).padEnd(6)} ${status.padEnd(10)} ${duration.padEnd(8)} ${title}`);
+    }
+  }
+
+  // ── Alerts ──
+  if (alerts.length > 0) {
+    console.log("\nALERTS");
+    console.log("-".repeat(80));
+    for (const alert of alerts) {
+      console.log(`  ${alert}`);
+    }
+  }
+}
+
 async function main(): Promise<void> {
   const args = stripProjectFlag(process.argv.slice(2));
   const command = args[0];
@@ -2350,6 +2458,9 @@ Examples:
     case "doctor":
       await cmdDoctor();
       break;
+    case "dashboard":
+      await cmdDashboard();
+      break;
     case "wiki": {
       const wikiSub = args[1];
       if (wikiSub === "setup") {

package/src/local-agent/codex-runner.ts

@@ -75,6 +75,7 @@ export class CodexRunner implements AgentRunner {
       preamble: this.agentDefinition?.prompt.preamble,
       append: this.agentDefinition?.prompt.append,
       labels: this.agentDefinition?.labels,
+      labelMismatchHint: context?.labelMismatchHint,
       // skills injected via .agent_context/skills/*.md files, not in prompt
     });
     const codexCommand = resolveCodexCommand(this.env);
@@ -161,6 +162,7 @@ export class CodexRunner implements AgentRunner {
       preamble: this.agentDefinition?.prompt.preamble,
       append: this.agentDefinition?.prompt.append,
       labels: this.agentDefinition?.labels,
+      labelMismatchHint: context?.labelMismatchHint,
     });
     const codexCommand = resolveCodexCommand(this.env);
 

package/src/local-agent/report.ts

@@ -25,6 +25,10 @@ export interface ReportResult {
     timestamp: string;
     error?: string;
   }[];
+  insights?: {
+    frequentFiles: { file: string; count: number }[];
+    retryHotspots: { issueIid: number; retryCount: number }[];
+  };
 }
 
 export async function generateReport(
@@ -95,6 +99,45 @@ export async function generateReport(
       error: e.error
     }));
 
+  // Pattern insights (HX-3)
+  // Frequent files: from git log
+  const frequentFiles: { file: string; count: number }[] = [];
+  try {
+    const { execFile: execFileCb } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execFileAsync = promisify(execFileCb);
+    const sinceStr = `${sinceDays} days ago`;
+    const { stdout } = await execFileAsync("git", [
+      "log", "--since", sinceStr, "--name-only", "--pretty=format:", "--diff-filter=M"
+    ], { maxBuffer: 1024 * 1024 });
+    const fileCounts = new Map<string, number>();
+    for (const line of stdout.toString().split("\n")) {
+      const f = line.trim();
+      if (f && f.startsWith("src/")) {
+        fileCounts.set(f, (fileCounts.get(f) ?? 0) + 1);
+      }
+    }
+    const sorted = [...fileCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+    for (const [file, count] of sorted) {
+      frequentFiles.push({ file, count });
+    }
+  } catch {
+    // git not available or not a git repo — skip
+  }
+
+  // Retry hotspots: issues that appear multiple times in events
+  const issueOccurrences = new Map<number, number>();
+  for (const e of events) {
+    if (e.issueIid) {
+      issueOccurrences.set(e.issueIid, (issueOccurrences.get(e.issueIid) ?? 0) + 1);
+    }
+  }
+  const retryHotspots = [...issueOccurrences.entries()]
+    .filter(([_, count]) => count > 1)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([issueIid, retryCount]) => ({ issueIid, retryCount }));
+
   return {
     agentName,
     period: { from: sinceDate, to: now },
@@ -106,7 +149,8 @@ export async function generateReport(
     successRate,
     avgDurationMs,
     topFailures,
-    recentRuns
+    recentRuns,
+    insights: { frequentFiles, retryHotspots }
   };
 }
 
@@ -180,6 +224,27 @@ export function formatReport(result: ReportResult): string {
     }
   }
 
+  // Pattern insights (HX-3)
+  const insights = result.insights;
+  if (insights && (insights.frequentFiles.length > 0 || insights.retryHotspots.length > 0)) {
+    lines.push("", "PATTERN INSIGHTS");
+    lines.push("-".repeat(40));
+
+    if (insights.frequentFiles.length > 0) {
+      lines.push("Frequently modified:");
+      for (const f of insights.frequentFiles) {
+        lines.push(`  ${f.file} (${f.count}x)`);
+      }
+    }
+
+    if (insights.retryHotspots.length > 0) {
+      lines.push("Retry hotspots:");
+      for (const h of insights.retryHotspots) {
+        lines.push(`  #${h.issueIid} (${h.retryCount} runs)`);
+      }
+    }
+  }
+
   return lines.join("\n");
 }
 

package/src/local-agent/watcher.ts

@@ -474,34 +474,18 @@ export async function runWatcherCycle(
 
   const issue = await dependencies.gitlabClient.getIssue(candidate.projectId, candidate.issueIid);
 
-  // NT-4: Three-tier routing — classify @mention before trigger label check
-  const mentionType = classifyMention(candidate.body ?? "", issue.title, issue.labels, issue.description);
-
-  if (mentionType === "contextual" && dependencies.agentRunner.runContextual) {
-    logger.info(`NT-4 contextual reply for issue #${issue.iid}: "${issue.title}"`);
-    await updateAgentUserStatus(dependencies, "busy", `#${issue.iid}`);
-
-    try {
-      const result = await dependencies.agentRunner.runContextual(issue, candidate.body ?? "", { todoId: candidate.id });
-      logger.info(`Contextual reply completed for #${issue.iid}: ${result.summary.slice(0, 100)}`);
-    } catch (error) {
-      logger.warn(`Contextual reply failed for #${issue.iid}: ${String(error).slice(0, 200)}`);
-    }
-
-    await updateAgentUserStatus(dependencies, "idle", undefined, config);
-    state.processedTodoIds = rememberIds(state.processedTodoIds, candidate.id);
-    state.activeRun = undefined;
-    await dependencies.stateStore.save(state);
-    try { await dependencies.gitlabClient.markTodoDone(candidate.id); } catch { /* silent */ }
-
-    return { status: "completed", issueIid: issue.iid, summary: `Contextual reply for #${issue.iid}` };
-  }
-
-  // Label-based trigger filtering (full_work path only)
+  // Label mismatch: don't skip (P1: @mention must always get a response),
+  // but pass hint to agent so it can decide how to respond (P3: agent autonomy)
+  let labelMismatchHint: string | undefined;
   if (triggers && !matchesTriggerLabels(issue.labels, triggers.labels, triggers.exclude_labels)) {
-    logger.info(`Issue #${issue.iid} does not match trigger labels for agent "${config.agentDefinition?.name}", skipping.`);
-    return { status: "idle" };
+    const agentName = config.agentDefinition?.name ?? "agent";
+    const required = triggers.labels?.join(", ") || "(无)";
+    const excluded = triggers.exclude_labels?.join(", ") || "(无)";
+    const actual = issue.labels.join(", ") || "(无)";
+    labelMismatchHint = `此 issue 的 label [${actual}] 不在 ${agentName} 的触发范围内（要求: [${required}]，排除: [${excluded}]）。你仍然需要回复这个 @mention（P1），但可以选择只回复说明而不执行代码修改。`;
+    logger.info(`Issue #${issue.iid}: label mismatch, passing hint to agent`);
   }
+
   const worktree = await dependencies.worktreeManager.ensureWorktree(issue.iid, issue.title);
 
   state.activeRun = {
@@ -582,7 +566,7 @@ export async function runWatcherCycle(
 
   try {
     const raceResult = await Promise.race([
-      dependencies.agentRunner.run(issue, worktree, { todoId: candidate.id, signal: abortController.signal }).then(r => ({ type: "completed" as const, result: r })),
+      dependencies.agentRunner.run(issue, worktree, { todoId: candidate.id, signal: abortController.signal, labelMismatchHint }).then(r => ({ type: "completed" as const, result: r })),
       closeDetection.then(() => ({ type: "closed" as const }))
     ]);
 
@@ -740,17 +724,21 @@ export async function runConcurrentWatcherCycle(
 
     if (result.error) {
       // Failed
-      logger.error(`Agent failed issue #${issueIid} after ${durationSec}s. Error: ${result.error.slice(0, 200)}`);
-      try {
-        await dependencies.gitlabClient.updateIssueLabels(
-          spawned.issue.projectId, issueIid,
-          transitionStatusLabels(spawned.issue.labels, getLabelConfig(config).error, getStatusLabelsList(config))
-        );
-        await dependencies.gitlabClient.addIssueNote(
-          spawned.issue.projectId, issueIid,
-          `⚠️ Agent 执行失败。\n\n${result.summary}`
-        );
-      } catch (e) { logger.warn(`Post-run cleanup failed: ${String(e).slice(0, 100)}`); }
+      const isMr = spawned.todo.targetType === "MergeRequest";
+      const targetLabel = isMr ? `MR !${issueIid}` : `issue #${issueIid}`;
+      logger.error(`Agent failed ${targetLabel} after ${durationSec}s. Error: ${result.error.slice(0, 200)}`);
+      if (!isMr) {
+        try {
+          await dependencies.gitlabClient.updateIssueLabels(
+            spawned.issue.projectId, issueIid,
+            transitionStatusLabels(spawned.issue.labels, getLabelConfig(config).error, getStatusLabelsList(config))
+          );
+          await dependencies.gitlabClient.addIssueNote(
+            spawned.issue.projectId, issueIid,
+            `⚠️ Agent 执行失败。\n\n${result.summary}`
+          );
+        } catch (e) { logger.warn(`Post-run cleanup failed: ${String(e).slice(0, 100)}`); }
+      }
       await notifyFailed(config.agentDefinition?.name ?? "agent", issueIid, spawned.issue.title, result.summary, config.webhookUrl);
       // Feishu: update card to failed state
       if (dependencies.feishuClient && spawned.feishuMessageId) {
@@ -833,34 +821,35 @@ export async function runConcurrentWatcherCycle(
     if (!candidate) break;
     processedInThisCycle.add(candidate.id);
 
-    // Skip MR todos and contextual replies in concurrent mode — handle them synchronously
     const isIssueTodo = candidate.targetType === "Issue";
-    if (!isIssueTodo) {
-      // Mark as processed, skip for now (MR handling stays synchronous)
-      state.processedTodoIds = rememberIds(state.processedTodoIds, candidate.id);
-      try { await dependencies.gitlabClient.markTodoDone(candidate.id); } catch { /* silent */ }
-      continue;
-    }
-
-    const issue = await dependencies.gitlabClient.getIssue(candidate.projectId, candidate.issueIid);
+    const targetIid = isIssueTodo ? candidate.issueIid : (candidate.targetIid ?? 0);
 
-    // Check mention type — contextual replies still run synchronously
-    const mentionType = classifyMention(candidate.body ?? "", issue.title, issue.labels, issue.description);
-    if (mentionType === "contextual" && dependencies.agentRunner.runContextual) {
-      // Run contextual reply synchronously (quick, non-blocking conceptually)
-      try {
-        await dependencies.agentRunner.runContextual(issue, candidate.body ?? "", { todoId: candidate.id });
-        logger.info(`Contextual reply completed for #${issue.iid}`);
-      } catch (e) { logger.warn(`Contextual reply failed: ${String(e).slice(0, 100)}`); }
-      state.processedTodoIds = rememberIds(state.processedTodoIds, candidate.id);
-      try { await dependencies.gitlabClient.markTodoDone(candidate.id); } catch { /* silent */ }
-      continue;
+    // Build issue object — real for Issues, synthetic for MRs
+    let issue: GitlabIssue;
+    if (isIssueTodo) {
+      issue = await dependencies.gitlabClient.getIssue(candidate.projectId, candidate.issueIid);
+    } else {
+      issue = {
+        id: 0,
+        iid: targetIid,
+        projectId: candidate.projectId,
+        title: `MR !${targetIid} @mention`,
+        description: candidate.body ?? "",
+        labels: [],
+        webUrl: candidate.targetUrl ?? ""
+      };
+      logger.info(`MR todo !${targetIid}: spawning into slot`);
     }
 
-    // Label trigger check
-    if (triggers && !matchesTriggerLabels(issue.labels, triggers.labels, triggers.exclude_labels)) {
-      logger.info(`Issue #${issue.iid} does not match trigger labels, skipping.`);
-      continue;
+    // Label mismatch: pass hint to agent (P1: always respond, P3: agent decides)
+    let labelMismatchHint: string | undefined;
+    if (isIssueTodo && triggers && !matchesTriggerLabels(issue.labels, triggers.labels, triggers.exclude_labels)) {
+      const agentName = config.agentDefinition?.name ?? "agent";
+      const required = triggers.labels?.join(", ") || "(无)";
+      const excluded = triggers.exclude_labels?.join(", ") || "(无)";
+      const actual = issue.labels.join(", ") || "(无)";
+      labelMismatchHint = `此 issue 的 label [${actual}] 不在 ${agentName} 的触发范围内（要求: [${required}]，排除: [${excluded}]）。你仍然需要回复这个 @mention（P1），但可以选择只回复说明而不执行代码修改。`;
+      logger.info(`Issue #${issue.iid}: label mismatch, passing hint to agent`);
     }
 
     // Ensure spawn() is available
@@ -870,7 +859,8 @@ export async function runConcurrentWatcherCycle(
     }
 
     // Prepare and spawn
-    const worktree = await dependencies.worktreeManager.ensureWorktree(issue.iid, issue.title);
+    const worktreeTitle = isIssueTodo ? issue.title : `mr-${targetIid}`;
+    const worktree = await dependencies.worktreeManager.ensureWorktree(targetIid, worktreeTitle);
 
     const skills = config.agentDefinition?.skills ?? [];
     if (skills.length > 0) {
@@ -880,7 +870,7 @@ export async function runConcurrentWatcherCycle(
       } catch (err) { logger.warn(`Failed to inject skill files: ${String(err)}`); }
     }
 
-    const spawnedRun = await dependencies.agentRunner.spawn(issue, worktree, { todoId: candidate.id });
+    const spawnedRun = await dependencies.agentRunner.spawn(issue, worktree, { todoId: candidate.id, labelMismatchHint });
     const now = new Date().toISOString();
 
     spawnedRuns.set(issue.iid, {
@@ -919,7 +909,7 @@ export async function runConcurrentWatcherCycle(
     }
 
     // Set up progress callback for webhook and/or feishu card updates
-    if ((config.webhookUrl || dependencies.feishuClient) && spawnedRun.onProgress !== undefined) {
+    if (config.webhookUrl || dependencies.feishuClient) {
       const agentName = config.agentDefinition?.name ?? "agent";
       const issueRef = `#${issue.iid}`;
       const capturedIssueIid = issue.iid;
@@ -1057,7 +1047,9 @@ async function finalizeTodo(
   const durationMs = new Date(finishedAt).getTime() - new Date(startedAt).getTime();
 
   // P11 post-run compensation: agent is probabilistic, verify critical state transitions
-  if (result.status === "completed") {
+  // Skip for MR todos — MRs don't have issue labels/notes to compensate
+  const isMrTodo = todo.targetType === "MergeRequest";
+  if (result.status === "completed" && !isMrTodo) {
     try {
       const freshIssue = await dependencies.gitlabClient.getIssue(issue.projectId, issue.iid);
       const logger = dependencies.logger ?? console;
@@ -1087,23 +1079,25 @@ async function finalizeTodo(
     }
   }
 
-  // NT-1: Post structured run summary note to GitLab issue (history visible in GitLab)
+  // NT-1: Post structured run summary note to GitLab (history visible in GitLab)
   // Posted AFTER agent reply and P11 compensation so it appears last in the timeline
-  try {
-    const durationStr = durationMs < 60000
-      ? `${Math.round(durationMs / 1000)}s`
-      : `${Math.round(durationMs / 60000)}m ${Math.round((durationMs % 60000) / 1000)}s`;
-    const statusEmoji = result.status === "completed" ? "✅" : "❌";
-    const noteBody = [
-      `${statusEmoji} **Agent run ${result.status}** (${durationStr})`,
-      "",
-      result.summary.slice(0, 500),
-      "",
-      `<!-- agent-run-log ${JSON.stringify({ agent: _config.agentDefinition?.name, status: result.status, startedAt, finishedAt, durationMs, branch: result.branch })} -->`
-    ].join("\n");
-    await dependencies.gitlabClient.addIssueNote(issue.projectId, issue.iid, noteBody);
-  } catch (err) {
-    (dependencies.logger ?? console).warn(`Failed to post run summary note: ${String(err)}`);
+  if (!isMrTodo) {
+    try {
+      const durationStr = durationMs < 60000
+        ? `${Math.round(durationMs / 1000)}s`
+        : `${Math.round(durationMs / 60000)}m ${Math.round((durationMs % 60000) / 1000)}s`;
+      const statusEmoji = result.status === "completed" ? "✅" : "❌";
+      const noteBody = [
+        `${statusEmoji} **Agent run ${result.status}** (${durationStr})`,
+        "",
+        result.summary.slice(0, 500),
+        "",
+        `<!-- agent-run-log ${JSON.stringify({ agent: _config.agentDefinition?.name, status: result.status, startedAt, finishedAt, durationMs, branch: result.branch })} -->`
+      ].join("\n");
+      await dependencies.gitlabClient.addIssueNote(issue.projectId, issue.iid, noteBody);
+    } catch (err) {
+      (dependencies.logger ?? console).warn(`Failed to post run summary note: ${String(err)}`);
+    }
   }
 
   appendRunHistory(state, {
@@ -1511,13 +1505,17 @@ function pickNextTodo(
   const acceptedActions = triggerActions ?? ACCEPTED_TODO_ACTIONS;
 
   const candidates = todos.filter((todo) => {
+    const todoLabel = todo.targetType === "MergeRequest"
+      ? `MR !${todo.targetIid ?? 0}`
+      : `issue #${todo.issueIid}`;
+
     if (processedTodos.has(todo.id)) {
-      logger?.info?.(`Todo ${todo.id} (issue #${todo.issueIid}): skipped — already processed`);
+      logger?.info?.(`Todo ${todo.id} (${todoLabel}): skipped — already processed`);
       return false;
     }
 
     if (!acceptedActions.has(todo.actionName)) {
-      logger?.info?.(`Todo ${todo.id} (issue #${todo.issueIid}): skipped — action "${todo.actionName}" not in triggers`);
+      logger?.info?.(`Todo ${todo.id} (${todoLabel}): skipped — action "${todo.actionName}" not in triggers`);
       return false;
     }
 
@@ -1525,8 +1523,10 @@ function pickNextTodo(
       return false;
     }
 
-    if (activeIssueIids?.has(todo.issueIid)) {
-      logger?.info?.(`Todo ${todo.id} (issue #${todo.issueIid}): skipped — already being processed`);
+    // For MR todos, check by targetIid; for Issues, check by issueIid
+    const effectiveIid = todo.targetType === "MergeRequest" ? (todo.targetIid ?? 0) : todo.issueIid;
+    if (activeIssueIids?.has(effectiveIid)) {
+      logger?.info?.(`Todo ${todo.id} (${todoLabel}): skipped — already being processed`);
       return false;
     }