glab-agent 0.2.10 → 0.2.12

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.10",
+  "version": "0.2.12",
   "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,12 @@ 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;
+  /** Path to the target project's repo (cached bare clone). Used by runners for git operations. */
+  targetRepoPath?: string;
+  /** Override gitlabProjectId for the prompt (target project, not agents repo) */
+  gitlabProjectId?: number;
 }
 
 export interface SpawnedRunResult {
@@ -116,6 +122,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 {
@@ -226,7 +234,9 @@ export function buildBasePrompt(ctx: AgentPromptContext): string {
     "",
     "## 当前环境",
     `- 分支: ${ctx.branch}`,
-    "- 工作目录: 项目的独立工作副本",
+    "- 工作目录: issue 对应项目的独立工作副本",
+    "- 如果任务涉及其他仓库，可以用 git clone 拉取（GITLAB_TOKEN 已配置，支持认证）",
+    ctx.labelMismatchHint ? `\n## 注意\n${ctx.labelMismatchHint}` : "",
     "",
     "## 最终输出",
     "标准输出不超过 5 行的简短总结（不是 GitLab 评论）。"

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

@@ -67,7 +67,7 @@ export class ClaudeRunner implements AgentRunner {
       issueIid: issue.iid,
       issueTitle: issue.title,
       gitlabHost: this.gitlabHost,
-      gitlabProjectId: this.gitlabProjectId,
+      gitlabProjectId: context?.gitlabProjectId ?? this.gitlabProjectId,
       worktreePath: worktree.worktreePath,
       branch: worktree.branch,
       provider: "claude",
@@ -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);
@@ -150,7 +151,7 @@ export class ClaudeRunner implements AgentRunner {
       issueIid: issue.iid,
       issueTitle: issue.title,
       gitlabHost: this.gitlabHost,
-      gitlabProjectId: this.gitlabProjectId,
+      gitlabProjectId: context?.gitlabProjectId ?? this.gitlabProjectId,
       worktreePath: worktree.worktreePath,
       branch: worktree.branch,
       provider: "claude",
@@ -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

@@ -67,7 +67,7 @@ export class CodexRunner implements AgentRunner {
       issueIid: issue.iid,
       issueTitle: issue.title,
       gitlabHost: this.gitlabHost,
-      gitlabProjectId: this.gitlabProjectId,
+      gitlabProjectId: context?.gitlabProjectId ?? this.gitlabProjectId,
       worktreePath: worktree.worktreePath,
       branch: worktree.branch,
       provider: "codex",
@@ -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);
@@ -153,7 +154,7 @@ export class CodexRunner implements AgentRunner {
       issueIid: issue.iid,
       issueTitle: issue.title,
       gitlabHost: this.gitlabHost,
-      gitlabProjectId: this.gitlabProjectId,
+      gitlabProjectId: context?.gitlabProjectId ?? this.gitlabProjectId,
       worktreePath: worktree.worktreePath,
       branch: worktree.branch,
       provider: "codex",
@@ -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/gitlab-glab-client.ts

@@ -101,7 +101,7 @@ export interface GitlabClient {
   getWikiPage(projectId: number | string, slug: string): Promise<WikiPage>;
   createWikiPage(projectId: number | string, title: string, content: string): Promise<WikiPage>;
   updateWikiPage(projectId: number | string, slug: string, title: string, content: string): Promise<WikiPage>;
-  getProject(projectIdOrPath: number | string): Promise<{ id: number } | undefined>;
+  getProject(projectIdOrPath: number | string): Promise<{ id: number; httpUrlToRepo?: string; pathWithNamespace?: string } | undefined>;
   createProject(name: string, options?: { visibility?: string; initializeWithReadme?: boolean }): Promise<{ id: number }>;
   getRepositoryFile(projectId: number | string, filePath: string, ref?: string): Promise<{ content: string } | undefined>;
   createOrUpdateRepositoryFile(projectId: number | string, filePath: string, content: string, commitMessage: string, options?: { create?: boolean }): Promise<void>;
@@ -723,13 +723,18 @@ export class GitlabGlabClient implements GitlabClient {
     };
   }
 
-  async getProject(projectIdOrPath: number | string): Promise<{ id: number } | undefined> {
+  async getProject(projectIdOrPath: number | string): Promise<{ id: number; httpUrlToRepo?: string; pathWithNamespace?: string } | undefined> {
     try {
       const encoded = typeof projectIdOrPath === "string" ? encodeURIComponent(projectIdOrPath) : projectIdOrPath;
       const payload = await this.readJson(`projects/${encoded}`);
       const p = (payload ?? {}) as Payload;
       const id = Number(p.id);
-      return Number.isNaN(id) ? undefined : { id };
+      if (Number.isNaN(id)) return undefined;
+      return {
+        id,
+        httpUrlToRepo: typeof p.http_url_to_repo === "string" ? p.http_url_to_repo as string : undefined,
+        pathWithNamespace: typeof p.path_with_namespace === "string" ? p.path_with_namespace as string : undefined,
+      };
     } catch {
       return undefined;
     }

package/src/local-agent/repo-cache.ts

@@ -122,6 +122,21 @@ export class RepoCache {
     return true;
   }
 
+  /**
+   * Build a git clone URL with embedded token for authentication.
+   * e.g., https://oauth2:TOKEN@gitlab.example.com/group/project.git
+   */
+  static authenticatedUrl(httpUrl: string, token: string): string {
+    try {
+      const url = new URL(httpUrl);
+      url.username = "oauth2";
+      url.password = token;
+      return url.toString();
+    } catch {
+      return httpUrl;
+    }
+  }
+
   /**
    * Get the cache directory path for a given repo URL.
    * Uses SHA-256 hash of the URL for the directory name.

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

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
 import path from "node:path";
 
 import { AgentRunnerError, type AgentRunner, type SpawnedRun } from "./agent-runner.js";
@@ -33,6 +34,7 @@ import { rotateIfNeeded } from "./log-rotate.js";
 import { validateToken } from "./token-check.js";
 import { WorktreeManager } from "./worktree-manager.js";
 import type { WorktreeInfo } from "./worktree-manager.js";
+import { RepoCache } from "./repo-cache.js";
 import { injectSkillFiles } from "./skill-inject.js";
 import { startHealthServer } from "./health-server.js";
 import type { HealthStatus } from "./health-server.js";
@@ -103,6 +105,8 @@ export interface WatcherDependencies {
   issueCloseCheckIntervalMs?: number;
   /** Feishu app client for targeted personal notifications */
   feishuClient?: import("./feishu-client.js").FeishuClient;
+  /** Cache for bare clones of target project repos */
+  repoCache?: RepoCache;
 }
 
 export interface WatcherCycleResult {
@@ -338,6 +342,52 @@ async function replaceReactionOnTodo(
   }
 }
 
+/**
+ * Resolve the target project's repo and create a worktree for the given issue/MR.
+ * Uses RepoCache to clone/fetch the target project, then creates a worktree from it.
+ * Falls back to the agents repo worktree if the target project can't be resolved.
+ */
+async function resolveTargetWorktree(
+  projectId: number,
+  iid: number,
+  title: string,
+  config: LocalAgentConfig,
+  dependencies: WatcherDependencies,
+  logger: Logger | typeof console
+): Promise<{ worktree: WorktreeInfo }> {
+  if (dependencies.repoCache) {
+    try {
+      const project = await dependencies.gitlabClient.getProject(projectId);
+      if (project?.httpUrlToRepo) {
+        const authedUrl = RepoCache.authenticatedUrl(project.httpUrlToRepo, config.gitlabToken);
+        const cachedRepoPath = await dependencies.repoCache.ensureRepo(authedUrl);
+
+        const agentName = config.agentDefinition?.name;
+        const worktreeRoot = path.join(config.agentRepoPath, ".glab-agent", "worktrees", agentName ?? "agent");
+
+        await mkdir(worktreeRoot, { recursive: true });
+
+        // Use a WorktreeManager pointing at the cached bare repo
+        const targetWtm = new WorktreeManager({
+          repoPath: cachedRepoPath,
+          worktreeRoot,
+          agentName,
+        });
+        const worktree = await targetWtm.ensureWorktree(iid, title);
+
+        (logger as Logger | undefined)?.info?.(`Target repo resolved: ${project.pathWithNamespace ?? projectId} → ${cachedRepoPath}`);
+        return { worktree };
+      }
+    } catch (err) {
+      (logger as Logger | undefined)?.warn?.(`Failed to resolve target repo for project ${projectId}, falling back to agents repo: ${String(err).slice(0, 150)}`);
+    }
+  }
+
+  // Fallback: use agents repo worktree (original behavior)
+  const worktree = await dependencies.worktreeManager.ensureWorktree(iid, title);
+  return { worktree };
+}
+
 export async function runWatcherCycle(
   config: LocalAgentConfig,
   dependencies: WatcherDependencies
@@ -429,7 +479,9 @@ export async function runWatcherCycle(
       webUrl: ""
     };
 
-    const worktree = await dependencies.worktreeManager.ensureWorktree(targetIid, `mr-${targetIid}`);
+    const { worktree } = await resolveTargetWorktree(
+      candidate.projectId, targetIid, `mr-${targetIid}`, config, dependencies, logger
+    );
     state.activeRun = {
       pid,
       todoId: candidate.id,
@@ -456,7 +508,7 @@ export async function runWatcherCycle(
     logger.info(`Starting agent for MR !${targetIid} branch=${worktree.branch}`);
 
     try {
-      const result = await dependencies.agentRunner.run(issue, worktree, { todoId: candidate.id });
+      const result = await dependencies.agentRunner.run(issue, worktree, { todoId: candidate.id, gitlabProjectId: candidate.projectId });
       logger.info(`Agent completed MR !${targetIid}. Summary: ${result.summary.slice(0, 200)}`);
     } catch (error) {
       const summary = error instanceof AgentRunnerError ? error.summary : String(error);
@@ -474,35 +526,21 @@ 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);
+
+  const { worktree } = await resolveTargetWorktree(
+    issue.projectId, issue.iid, issue.title, config, dependencies, logger
+  );
 
   state.activeRun = {
     pid,
@@ -582,7 +620,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, gitlabProjectId: issue.projectId }).then(r => ({ type: "completed" as const, result: r })),
       closeDetection.then(() => ({ type: "closed" as const }))
     ]);
 
@@ -740,17 +778,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 +875,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 targetIid = isIssueTodo ? candidate.issueIid : (candidate.targetIid ?? 0);
 
-    const issue = await dependencies.gitlabClient.getIssue(candidate.projectId, candidate.issueIid);
-
-    // 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 +913,11 @@ 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 resolveTargetWorktree(
+      isIssueTodo ? issue.projectId : candidate.projectId,
+      targetIid, worktreeTitle, config, dependencies, logger
+    );
 
     const skills = config.agentDefinition?.skills ?? [];
     if (skills.length > 0) {
@@ -880,7 +927,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, gitlabProjectId: isIssueTodo ? issue.projectId : candidate.projectId });
     const now = new Date().toISOString();
 
     spawnedRuns.set(issue.iid, {
@@ -1057,7 +1104,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 +1136,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 +1562,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 +1580,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;
     }
 
@@ -1602,6 +1659,9 @@ function createDependencies(config: LocalAgentConfig, logger?: Logger): WatcherD
       agentName: config.agentDefinition?.name
     }),
     agentRunner,
+    repoCache: new RepoCache({
+      cacheDir: path.join(config.agentRepoPath, ".glab-agent", "repo-cache")
+    }),
     logger
   };
 }
@@ -1805,9 +1865,8 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
     config.botName = botUser.name;
     logger.info(`Token validated. Bot identity: @${botUser.username} (${botUser.name})`);
 
-    // Update GitLab user bio with agent profile (P1: Agent = 员工)
+    // Update GitLab user profile (P1: Agent = 员工)
     await updateAgentUserBio(config, dependencies);
-    await publishAgentProfileWiki(config, dependencies);
     await publishProfileReadme(config, dependencies);
     await updateAgentUserStatus(dependencies, "idle", undefined, config);
   } catch (error) {