glab-agent 0.1.0

package/src/local-agent/cli.ts

@@ -0,0 +1,1497 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, existsSync } from "node:fs";
+import { writeFile, mkdir, readFile } from "node:fs/promises";
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+
+import { discoverAgents, loadAgentByName, agentAgentsDir, agentEnvPath, agentBaseDir, agentLogPath, agentStatePath, agentWorktreeRoot, discoverSharedSkills, agentSkillsDir, agentHeartbeatPath } from "./agent-config.js";
+import { readHeartbeat, isHeartbeatStale } from "./heartbeat.js";
+import { FileStateStore, appendRunHistory } from "./state-store.js";
+import type { RunHistoryEntry } from "./state-store.js";
+import { GitlabGlabClient } from "./gitlab-glab-client.js";
+import { loadConfigFromAgentDefinition, transitionStatusLabels, markAgentOffline, parseGitRemoteUrl } from "./watcher.js";
+import { sendNotification } from "./notifier.js";
+import { generateReport, formatReport } from "./report.js";
+import { parseGitHubUrl, importSkill, importAllSkills } from "./skill-import.js";
+import { initWikiDir, wikiPath } from "./wiki-sync.js";
+
+const execFileAsync = promisify(execFileCb);
+
+// Load .env file into process.env (simple dotenv without dependency)
+function loadDotenv(filePath: string): void {
+  try {
+    const content = readFileSync(filePath, "utf8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eqIdx = trimmed.indexOf("=");
+      if (eqIdx <= 0) continue;
+      const key = trimmed.slice(0, eqIdx).trim();
+      const value = trimmed.slice(eqIdx + 1).trim();
+      if (!(key in process.env)) {
+        process.env[key] = value;
+      }
+    }
+  } catch {
+    // .env not found, ignore
+  }
+}
+
+// Parse --project <dir> early, before loadDotenv
+function parseProjectFlag(argv: string[]): string | undefined {
+  const idx = argv.indexOf("--project");
+  if (idx !== -1 && idx + 1 < argv.length) {
+    return path.resolve(argv[idx + 1]);
+  }
+  return undefined;
+}
+
+function stripProjectFlag(args: string[]): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--project") {
+      i++; // skip the value too
+    } else {
+      result.push(args[i]);
+    }
+  }
+  return result;
+}
+
+// INSTALL_DIR: the glab-agent repo (2 levels up from src/local-agent/cli.ts)
+const INSTALL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+// SCRIPT_DIR: always points to src/local-agent/ in the glab-agent repo
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+// PROJECT_DIR: target project directory (--project flag or cwd)
+const PROJECT_DIR = parseProjectFlag(process.argv) ?? process.cwd();
+const AGENTS_DIR = agentAgentsDir(PROJECT_DIR);
+
+loadDotenv(agentEnvPath(PROJECT_DIR));
+import {
+  getAgentStatus,
+  startAgent,
+  stopAgent,
+  generateLaunchdPlist,
+  launchdPlistPath
+} from "./process-manager.js";
+
+function usage(): void {
+  console.log(`Usage: glab-agent <command> [--project <dir>] [options]
+       pnpm agent <command> [--project <dir>] [options]
+
+Options:
+  --project <dir>        Target project directory (default: cwd)
+
+Commands:
+  init [name]            Initialize .glab-agent/ and optionally create an agent
+                           --provider <claude|codex>  --labels <l1,l2>  --token-env <VAR>
+  list                   List all agent definitions
+  start <name|--all>     Start agent(s) as background watcher process
+  stop <name|--all>      Stop agent(s)
+  status [name]          Show agent status (PID, alive)
+  logs <name>            Tail agent logs
+  run-once <name>        Run a single watcher cycle
+  cancel <name>          Cancel current running task
+  retry <name> <iid>     Retry a failed issue (--resume to keep worktree)
+  why <issue-iid>        Diagnose why an issue hasn't been picked up
+  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)
+  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)
+  skills                 List all shared skills
+  skills import <url>    Import skills from GitHub repo (--force to overwrite)
+  wiki init              Initialize Knowledge Wiki directory structure
+  doctor                 Check prerequisites and environment
+`);
+}
+
+async function cmdList(): Promise<void> {
+  const agents = await discoverAgents(AGENTS_DIR);
+  if (agents.length === 0) {
+    console.log("No agent definitions found in agents/*.yaml");
+    console.log("Create a YAML file in the agents/ directory to define an agent.");
+    return;
+  }
+
+  console.log(`Found ${agents.length} agent(s):\n`);
+  for (const agent of agents) {
+    const status = await getAgentStatus(PROJECT_DIR, agent.name);
+    const statusIcon = status.alive ? "🟢" : "⚫";
+    const pidInfo = status.alive ? ` (PID ${status.pid})` : "";
+    console.log(`  ${statusIcon} ${agent.name}${pidInfo}`);
+    console.log(`     ${agent.display_name} — ${agent.description || "(no description)"}`);
+    console.log(`     provider: ${agent.provider} | poll: ${agent.poll_interval_seconds}s`);
+    if (agent.skills.length > 0) {
+      console.log(`     skills: ${agent.skills.map((s) => s.name).join(", ")}`);
+    }
+    if (agent.triggers.labels.length > 0) {
+      console.log(`     labels: ${agent.triggers.labels.join(", ")}`);
+    }
+    console.log();
+  }
+}
+
+async function cmdSkills(): Promise<void> {
+  const skillsDir = agentSkillsDir(PROJECT_DIR);
+  const skills = await discoverSharedSkills(skillsDir);
+  if (skills.length === 0) {
+    console.log("No shared skills found in .glab-agent/skills/");
+    console.log("Create skill YAML files to share across agents.");
+    return;
+  }
+  console.log(`Found ${skills.length} shared skill(s):\n`);
+  for (const skill of skills) {
+    console.log(`  ${skill.name}`);
+    if (skill.description) {
+      console.log(`     ${skill.description}`);
+    }
+    console.log();
+  }
+}
+
+async function cmdSkillImport(input: string, options?: { force?: boolean }): Promise<void> {
+  const skillsDir = agentSkillsDir(PROJECT_DIR);
+  const parsed = parseGitHubUrl(input);
+  if (!parsed) {
+    console.error(`Invalid GitHub URL or shorthand: ${input}`);
+    console.error("Supported formats: https://github.com/owner/repo, owner/repo, owner/repo/path/skill.yaml, owner/repo/path/SKILL.md");
+    process.exit(1);
+  }
+
+  const { owner, repo, path: filePath, ref } = parsed;
+
+  if (filePath && (filePath.endsWith(".yaml") || filePath.endsWith(".yml") || filePath.endsWith(".md"))) {
+    // Import a single skill file
+    const result = await importSkill(owner, repo, filePath, skillsDir, { ref, force: options?.force });
+    if (result.status === "failed") {
+      console.error(`  Failed: ${result.name} — ${result.message}`);
+      process.exit(1);
+    }
+    console.log(`  ${result.status === "imported" ? "+" : result.status === "updated" ? "~" : "="} ${result.name} — ${result.message}`);
+  } else {
+    // Import all skills from the repo
+    const results = await importAllSkills(owner, repo, skillsDir, { ref, force: options?.force });
+    if (results.length === 0) {
+      console.log("No skill files found in the repository.");
+      console.log("Searched: skills/, .agent_context/skills/, .glab-agent/skills/");
+      return;
+    }
+    for (const r of results) {
+      const icon = r.status === "imported" ? "+" : r.status === "updated" ? "~" : r.status === "failed" ? "x" : "=";
+      console.log(`  ${icon} ${r.name} — ${r.message}`);
+    }
+    const imported = results.filter(r => r.status === "imported" || r.status === "updated").length;
+    console.log(`\n${imported} skill(s) imported/updated to ${skillsDir}`);
+  }
+}
+
+async function cmdStart(nameOrFlag: string): Promise<void> {
+  if (nameOrFlag === "--all") {
+    const agents = await discoverAgents(AGENTS_DIR);
+    if (agents.length === 0) {
+      console.log("No agent definitions found.");
+      return;
+    }
+    for (const agent of agents) {
+      try {
+        const pid = await startAgent(PROJECT_DIR, agent.name, SCRIPT_DIR, INSTALL_DIR);
+        console.log(`Started ${agent.name} (PID ${pid})`);
+      } catch (error) {
+        console.error(`Failed to start ${agent.name}: ${String(error)}`);
+      }
+    }
+    return;
+  }
+
+  // Validate agent exists
+  await loadAgentByName(AGENTS_DIR, nameOrFlag);
+  const pid = await startAgent(PROJECT_DIR, nameOrFlag, SCRIPT_DIR, INSTALL_DIR);
+  console.log(`Started ${nameOrFlag} (PID ${pid})`);
+}
+
+async function markOffline(name: string): Promise<void> {
+  try {
+    const agent = await loadAgentByName(AGENTS_DIR, name);
+    const config = loadConfigFromAgentDefinition(agent, process.env, { cwd: PROJECT_DIR });
+    const client = new GitlabGlabClient({ host: config.gitlabHost, token: config.gitlabToken });
+    const store = new FileStateStore(agentStatePath(PROJECT_DIR, name));
+    await markAgentOffline(config, client, store);
+  } catch (err) {
+    console.warn(`Warning: could not update GitLab offline status for ${name}: ${String(err)}`);
+  }
+}
+
+async function cmdStop(nameOrFlag: string): Promise<void> {
+  if (nameOrFlag === "--all") {
+    const agents = await discoverAgents(AGENTS_DIR);
+    for (const agent of agents) {
+      const stopped = await stopAgent(PROJECT_DIR, agent.name);
+      console.log(stopped ? `Stopped ${agent.name}` : `${agent.name} was not running`);
+      await markOffline(agent.name);
+    }
+    return;
+  }
+
+  const stopped = await stopAgent(PROJECT_DIR, nameOrFlag);
+  console.log(stopped ? `Stopped ${nameOrFlag}` : `${nameOrFlag} was not running`);
+  await markOffline(nameOrFlag);
+}
+
+async function cmdCancel(name: string): Promise<void> {
+  const agent = await loadAgentByName(AGENTS_DIR, name);
+  const statePath = agentStatePath(PROJECT_DIR, name);
+  const store = new FileStateStore(statePath);
+  const state = await store.load();
+
+  if (!state.activeRun) {
+    console.log(`Agent ${name} 没有正在运行的任务。`);
+    return;
+  }
+
+  const { issueIid, startedAt, branch } = state.activeRun;
+  console.log(`正在取消 agent ${name} 对 issue #${issueIid} 的处理...`);
+
+  // 1. Stop the watcher process
+  await stopAgent(PROJECT_DIR, name);
+
+  // 2. Update GitLab issue: revert label to Todo and add cancellation note
+  const config = loadConfigFromAgentDefinition(agent, process.env, { cwd: PROJECT_DIR });
+  const client = new GitlabGlabClient({ host: config.gitlabHost, token: config.gitlabToken });
+
+  try {
+    const issue = await client.getIssue(config.gitlabProjectId!, issueIid);
+    if (issue.labels.includes("In Progress")) {
+      await client.updateIssueLabels(
+        config.gitlabProjectId!,
+        issueIid,
+        transitionStatusLabels(issue.labels, "Todo")
+      );
+    }
+    await client.addIssueNote(config.gitlabProjectId!, issueIid, "⏹️ 任务已被用户取消。");
+  } catch (err) {
+    console.warn(`更新 GitLab issue 失败: ${String(err)}`);
+  }
+
+  // 3. Record history and clear activeRun
+  appendRunHistory(state, {
+    issueIid,
+    status: "failed",
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    branch,
+    summary: "Cancelled by user"
+  });
+  state.activeRun = undefined;
+  state.lastRun = { status: "failed", at: new Date().toISOString(), issueIid, summary: "Cancelled by user" };
+  await store.save(state);
+
+  console.log(`已取消。Issue #${issueIid} 已回滚到 Todo 状态。`);
+}
+
+async function formatAgentStatus(agentName: string): Promise<string> {
+  const status = await getAgentStatus(PROJECT_DIR, agentName);
+  const icon = status.alive ? "🟢" : "⚫";
+  let statusText = status.alive ? `running (PID ${status.pid})` : "not running";
+
+  if (status.alive) {
+    const heartbeat = await readHeartbeat(agentHeartbeatPath(PROJECT_DIR, agentName));
+    if (heartbeat) {
+      const agent = await loadAgentByName(AGENTS_DIR, agentName);
+      if (isHeartbeatStale(heartbeat, agent.poll_interval_seconds)) {
+        statusText += " ⚠️  heartbeat stale";
+      } else {
+        statusText += ` (${heartbeat.cycleCount} cycles)`;
+      }
+      if (heartbeat.lastError) {
+        statusText += ` last_error: ${heartbeat.lastError.slice(0, 60)}`;
+      }
+    }
+  }
+
+  return `${icon} ${agentName}: ${statusText}`;
+}
+
+async function cmdStatus(name?: string): Promise<void> {
+  if (name) {
+    console.log(await formatAgentStatus(name));
+    return;
+  }
+
+  const agents = await discoverAgents(AGENTS_DIR);
+  if (agents.length === 0) {
+    console.log("No agent definitions found.");
+    return;
+  }
+  for (const agent of agents) {
+    console.log(await formatAgentStatus(agent.name));
+  }
+}
+
+async function cmdLogs(name: string): Promise<void> {
+  const logFile = path.join(agentLogPath(PROJECT_DIR, name), "watcher.log");
+  const { execFile } = await import("node:child_process");
+  const child = execFile("tail", ["-f", "-n", "50", logFile], { encoding: "utf8" });
+  child.stdout?.pipe(process.stdout);
+  child.stderr?.pipe(process.stderr);
+  await new Promise((resolve) => child.on("exit", resolve));
+}
+
+async function cmdRunOnce(name: string): Promise<void> {
+  // Import and run the watcher main with --agent flag
+  const { main } = await import("./watcher.js");
+  await main(["run-once", "--agent", name, "--project", PROJECT_DIR]);
+}
+
+async function cmdInstall(nameOrFlag: string): Promise<void> {
+  const install = async (agentName: string) => {
+    const plistContent = generateLaunchdPlist(agentName, PROJECT_DIR, SCRIPT_DIR, INSTALL_DIR);
+    const plistPath = launchdPlistPath(agentName, PROJECT_DIR);
+    await mkdir(path.dirname(plistPath), { recursive: true });
+    await writeFile(plistPath, plistContent, "utf8");
+    console.log(`Wrote ${plistPath}`);
+    console.log(`  Load:   launchctl load ${plistPath}`);
+    console.log(`  Unload: launchctl unload ${plistPath}`);
+  };
+
+  if (nameOrFlag === "--all") {
+    const agents = await discoverAgents(AGENTS_DIR);
+    for (const agent of agents) {
+      await install(agent.name);
+    }
+    return;
+  }
+
+  // Validate agent exists
+  await loadAgentByName(AGENTS_DIR, nameOrFlag);
+  await install(nameOrFlag);
+}
+
+function extractFlag(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+
+export function generateAgentYaml(
+  name: string,
+  provider: "claude" | "codex",
+  labels: string[],
+  tokenEnv: string,
+  options?: { host?: string }
+): string {
+  const displayName = name.split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+
+  const gitlabLines: string[] = [`gitlab:`];
+  if (options?.host) {
+    gitlabLines.push(`  host: ${options.host}`);
+  }
+  gitlabLines.push(`  token_env: ${tokenEnv}`);
+
+  const lines: string[] = [
+    `name: ${name}`,
+    `display_name: "${displayName}"`,
+    `description: ""`,
+    ``,
+    ...gitlabLines,
+    ``,
+    `provider: ${provider}`,
+    ``,
+    `prompt:`,
+    `  preamble: |`,
+    `    你是一个编码 agent，负责处理 GitLab issue。`,
+    ``,
+    `skills:`,
+    `  - test-before-commit`,
+    ``,
+    `triggers:`,
+    `  actions:`,
+    `    - mentioned`,
+    `    - directly_addressed`,
+  ];
+
+  if (labels.length > 0) {
+    lines.push(`  labels:`);
+    for (const label of labels) {
+      lines.push(`    - ${label}`);
+    }
+  }
+
+  lines.push(``, `poll_interval_seconds: 60`);
+
+  return lines.join("\n") + "\n";
+}
+
+export async function detectGitRemote(projectDir: string): Promise<{ host: string; projectPath: string } | undefined> {
+  try {
+    const { stdout } = await execFileAsync("git", ["-C", projectDir, "remote", "get-url", "origin"], { timeout: 5000 });
+    const remoteUrl = stdout.trim();
+    if (!remoteUrl) return undefined;
+    return parseGitRemoteUrl(remoteUrl);
+  } catch {
+    return undefined;
+  }
+}
+
+export async function validateGitlabToken(host: string, token: string): Promise<{ valid: boolean; username?: string }> {
+  try {
+    const { stdout } = await execFileAsync("glab", ["api", "/user"], {
+      timeout: 10_000,
+      env: { ...process.env, GITLAB_HOST: host, GITLAB_TOKEN: token }
+    });
+    const user = JSON.parse(stdout) as { username?: string };
+    return { valid: true, username: user.username };
+  } catch {
+    return { valid: false };
+  }
+}
+
+async function cmdInit(name?: string, options?: { provider?: string; labels?: string; tokenEnv?: string }): Promise<void> {
+  const base = agentBaseDir(PROJECT_DIR);
+  const dirs = [
+    path.join(base, "agents"),
+    path.join(base, "skills"),
+    path.join(base, "state"),
+    path.join(base, "pid"),
+    path.join(base, "logs"),
+    path.join(base, "worktrees"),
+    path.join(base, "metrics"),
+    path.join(base, "heartbeat"),
+  ];
+  for (const dir of dirs) {
+    await mkdir(dir, { recursive: true });
+  }
+
+  // Create .glab-agent/.gitignore for runtime artifacts
+  const gitignorePath = path.join(base, ".gitignore");
+  const gitignoreContent = `# Runtime artifacts (do not commit)
+state/
+pid/
+logs/
+worktrees/
+metrics/
+heartbeat/
+.env
+`;
+  // Only write if not exists
+  try {
+    await readFile(gitignorePath, "utf8");
+    console.log(`.glab-agent/.gitignore already exists, skipping.`);
+  } catch {
+    await writeFile(gitignorePath, gitignoreContent, "utf8");
+    console.log(`Created ${gitignorePath}`);
+  }
+
+  console.log(`Initialized ${base}/`);
+
+  // Auto-detect GitLab remote (silent failure is fine)
+  const remote = await detectGitRemote(PROJECT_DIR);
+
+  if (name) {
+    const provider = options?.provider ?? "claude";
+    if (provider !== "claude" && provider !== "codex") {
+      console.error(`Invalid provider "${provider}". Must be "claude" or "codex".`);
+      process.exit(1);
+    }
+
+    const labels = options?.labels ? options.labels.split(",").map(l => l.trim()) : [];
+    const tokenEnv = options?.tokenEnv ?? "GITLAB_TOKEN";
+    const yamlPath = path.join(base, "agents", `${name}.yaml`);
+
+    try {
+      await readFile(yamlPath, "utf8");
+      console.error(`Agent "${name}" already exists at ${yamlPath}`);
+      process.exit(1);
+    } catch { /* does not exist, continue */ }
+
+    if (remote) {
+      console.log(`检测到 GitLab: ${remote.host}/${remote.projectPath}`);
+    }
+
+    const yamlContent = generateAgentYaml(name, provider as "claude" | "codex", labels, tokenEnv, {
+      host: remote?.host
+    });
+    await writeFile(yamlPath, yamlContent, "utf8");
+    console.log(`Created agent definition: ${yamlPath}`);
+
+    // Validate token if available
+    const tokenValue = process.env[tokenEnv];
+    if (tokenValue && remote) {
+      console.log(`正在验证 ${tokenEnv}...`);
+      const validation = await validateGitlabToken(remote.host, tokenValue);
+      if (validation.valid) {
+        console.log(`✅ Token 有效，连接为 @${validation.username}`);
+      } else {
+        console.log(`⚠️  Token 验证失败，请检查 ${tokenEnv} 是否正确`);
+      }
+    }
+
+    console.log(`\nAgent "${name}" 已创建。`);
+    const steps: string[] = [];
+    if (!tokenValue) {
+      steps.push(`设置 token: echo "${tokenEnv}=glpat-xxx" >> ${path.join(base, ".env")}`);
+    }
+    steps.push(`自定义配置: edit ${yamlPath}`);
+    steps.push(`启动: pnpm agent start ${name}`);
+    steps.push(`验证: pnpm agent run-once ${name}`);
+    console.log("\n下一步:");
+    steps.forEach((s, i) => console.log(`  ${i + 1}. ${s}`));
+  } else {
+    if (remote) {
+      console.log(`\n检测到 GitLab 仓库: ${remote.host}/${remote.projectPath}`);
+    }
+    console.log(`\n下一步:`);
+    console.log(`  1. Create agent definition: ${path.join(base, "agents", "<name>.yaml")}`);
+    console.log(`  2. Add token: echo "GITLAB_TOKEN=glpat-xxx" > ${path.join(base, ".env")}`);
+    console.log(`  3. Verify: pnpm agent list --project ${PROJECT_DIR}`);
+  }
+}
+
+// ── Doctor command ──────────────────────────────────────────────────────────
+
+export interface DoctorCheckResult {
+  label: string;
+  ok: boolean;
+  optional: boolean;
+  message: string;
+}
+
+export async function checkToolVersion(
+  cmd: string,
+  args: string[],
+  label: string,
+  optional: boolean,
+  installHint?: string
+): Promise<DoctorCheckResult> {
+  try {
+    const { stdout, stderr } = await execFileAsync(cmd, args, { timeout: 10_000 });
+    const version = (stdout || stderr).trim().split("\n")[0];
+    return { label, ok: true, optional, message: version };
+  } catch {
+    const hint = installHint ? ` — install from ${installHint}` : "";
+    const suffix = optional ? " (optional)" : "";
+    return { label, ok: false, optional, message: `not found${suffix}${hint}` };
+  }
+}
+
+export function formatCheck(result: DoctorCheckResult): string {
+  if (result.ok) {
+    return `✅ ${result.label}: ${result.message}`;
+  }
+  const icon = result.optional ? "⚠️ " : "❌";
+  return `${icon} ${result.label}: ${result.message}`;
+}
+
+async function cmdDoctor(): Promise<void> {
+  console.log("glab-agent doctor");
+  console.log("==================\n");
+
+  const results: DoctorCheckResult[] = [];
+
+  // 1. git
+  results.push(
+    await checkToolVersion("git", ["--version"], "git", false, "https://git-scm.com")
+  );
+
+  // 2. glab
+  results.push(
+    await checkToolVersion("glab", ["--version"], "glab", false, "https://gitlab.com/gitlab-org/cli")
+  );
+
+  // 3. claude (optional)
+  results.push(
+    await checkToolVersion("claude", ["-v"], "claude", true)
+  );
+
+  // 4. codex (optional)
+  results.push(
+    await checkToolVersion("codex", ["--version"], "codex", true)
+  );
+
+  // 5. .glab-agent/ directory
+  const baseDir = agentBaseDir(PROJECT_DIR);
+  const baseDirExists = existsSync(baseDir);
+  results.push({
+    label: ".glab-agent/ directory",
+    ok: baseDirExists,
+    optional: false,
+    message: baseDirExists ? "exists" : `not found — run 'pnpm agent init'`
+  });
+
+  // 6. Agent definitions
+  let agents: Awaited<ReturnType<typeof discoverAgents>> = [];
+  try {
+    agents = await discoverAgents(AGENTS_DIR);
+  } catch {
+    // ignore
+  }
+  if (agents.length > 0) {
+    const names = agents.map((a) => a.name).join(", ");
+    results.push({
+      label: "Agent definitions",
+      ok: true,
+      optional: false,
+      message: `Found ${agents.length} agent definition(s): ${names}`
+    });
+  } else {
+    results.push({
+      label: "Agent definitions",
+      ok: false,
+      optional: false,
+      message: "no .yaml files found in .glab-agent/agents/"
+    });
+  }
+
+  // 7. .env file
+  const envPath = agentEnvPath(PROJECT_DIR);
+  const envExists = existsSync(envPath);
+  results.push({
+    label: ".env file",
+    ok: envExists,
+    optional: false,
+    message: envExists ? "exists" : "not found — create .glab-agent/.env with token variables"
+  });
+
+  // 8. Token validity for each agent definition
+  const seenTokenEnvs = new Set<string>();
+  let firstToken: { value: string; host?: string } | undefined;
+  for (const agent of agents) {
+    const tokenEnv = agent.gitlab.token_env;
+    if (seenTokenEnvs.has(tokenEnv)) continue;
+    seenTokenEnvs.add(tokenEnv);
+
+    const tokenValue = process.env[tokenEnv];
+    if (tokenValue && tokenValue.length > 0) {
+      results.push({
+        label: `Token ${tokenEnv}`,
+        ok: true,
+        optional: false,
+        message: "is set"
+      });
+      if (!firstToken) {
+        firstToken = { value: tokenValue, host: agent.gitlab.host };
+      }
+    } else {
+      results.push({
+        label: `Token ${tokenEnv}`,
+        ok: false,
+        optional: false,
+        message: `environment variable ${tokenEnv} is not set or empty`
+      });
+    }
+  }
+
+  // 9. GitLab API connectivity
+  if (firstToken) {
+    try {
+      const glabArgs = ["api", "/user"];
+      const glabEnv: NodeJS.ProcessEnv = { ...process.env, GITLAB_TOKEN: firstToken.value };
+      if (firstToken.host) {
+        glabEnv.GITLAB_HOST = firstToken.host;
+      }
+      const { stdout } = await execFileAsync("glab", glabArgs, {
+        timeout: 15_000,
+        env: glabEnv
+      });
+      const user = JSON.parse(stdout);
+      const username = user.username ?? "unknown";
+      const host = firstToken.host ?? "gitlab.com";
+      results.push({
+        label: "GitLab API",
+        ok: true,
+        optional: false,
+        message: `connected as @${username} to ${host}`
+      });
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      results.push({
+        label: "GitLab API",
+        ok: false,
+        optional: false,
+        message: `connection failed — ${errMsg}`
+      });
+    }
+  }
+
+  // Print results
+  for (const r of results) {
+    console.log(formatCheck(r));
+  }
+
+  // Summary
+  const issues = results.filter((r) => !r.ok && !r.optional);
+  console.log();
+  if (issues.length === 0) {
+    console.log("All checks passed!");
+  } else {
+    console.log(`${issues.length} issue(s) found.`);
+  }
+}
+
+// ── History command ─────────────────────────────────────────────────────────
+
+export function formatDuration(startedAt: string, finishedAt: string): string {
+  const ms = new Date(finishedAt).getTime() - new Date(startedAt).getTime();
+  const totalSeconds = Math.max(0, Math.round(ms / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  if (minutes > 0) return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+  return `${seconds}s`;
+}
+
+async function cmdHistory(name: string, last: number): Promise<void> {
+  // Validate agent exists
+  await loadAgentByName(AGENTS_DIR, name);
+
+  const statePath = agentStatePath(PROJECT_DIR, name);
+  const store = new FileStateStore(statePath);
+  const state = await store.load();
+
+  const history = state.runHistory ?? [];
+  if (history.length === 0) {
+    console.log(`Agent: ${name} -- No execution history found.`);
+    return;
+  }
+
+  const entries = history.slice(-last).reverse();
+  console.log(`Agent: ${name} -- Last ${Math.min(last, history.length)} runs\n`);
+
+  // Column headers
+  const numW = 4;
+  const issueW = 8;
+  const statusW = 11;
+  const durationW = 10;
+  const branchW = 40;
+
+  console.log(
+    `${"#".padEnd(numW)}${"Issue".padEnd(issueW)}${"Status".padEnd(statusW)}${"Duration".padEnd(durationW)}${"Branch".padEnd(branchW)}Title`
+  );
+  console.log("-".repeat(numW + issueW + statusW + durationW + branchW + 20));
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const num = String(i + 1).padEnd(numW);
+    const issueStr = `#${entry.issueIid}`.padEnd(issueW);
+    const statusStr = entry.status.padEnd(statusW);
+    const duration = formatDuration(entry.startedAt, entry.finishedAt).padEnd(durationW);
+    const branch = (entry.branch ?? "-").padEnd(branchW);
+    const title = entry.issueTitle ?? "";
+    console.log(`${num}${issueStr}${statusStr}${duration}${branch}${title}`);
+  }
+
+  // Summary
+  const total = history.length;
+  const completed = history.filter((e) => e.status === "completed").length;
+  const failed = history.filter((e) => e.status === "failed").length;
+
+  const durations = history.map((e) =>
+    new Date(e.finishedAt).getTime() - new Date(e.startedAt).getTime()
+  );
+  const avgMs = durations.reduce((a, b) => a + b, 0) / durations.length;
+  const avgSeconds = Math.round(avgMs / 1000);
+  const avgHours = Math.floor(avgSeconds / 3600);
+  const avgMinutes = Math.floor((avgSeconds % 3600) / 60);
+  const avgSecs = avgSeconds % 60;
+  let avgStr: string;
+  if (avgHours > 0) avgStr = `${avgHours}h ${avgMinutes}m`;
+  else if (avgMinutes > 0) avgStr = `${avgMinutes}m ${String(avgSecs).padStart(2, "0")}s`;
+  else avgStr = `${avgSecs}s`;
+
+  console.log(`\nTotal: ${total} runs | ${completed} completed | ${failed} failed | Avg duration: ${avgStr}`);
+}
+
+// ── Report command ────────────────────────────────────────────────────────
+
+async function cmdReport(name: string, sinceDays: number): Promise<void> {
+  const metricsDir = path.join(PROJECT_DIR, ".glab-agent", "metrics");
+  const result = await generateReport(metricsDir, name, { sinceDays });
+  console.log(formatReport(result));
+}
+
+// ── Watch command ─────────────────────────────────────────────────────────
+
+export function renderWatchScreen(
+  name: string,
+  status: { alive: boolean; pid?: number },
+  state: import("./state-store.js").LocalAgentState,
+  now: Date
+): string {
+  const lines: string[] = [];
+
+  lines.push(`glab-agent watch: ${name}                    [Ctrl+C 退出]`);
+  lines.push("\u2501".repeat(50));
+  lines.push("");
+
+  if (status.alive) {
+    lines.push(`状态:  🟢 运行中 (PID ${status.pid})`);
+  } else {
+    lines.push(`状态:  ⚫ 未运行`);
+  }
+
+  if (state.activeRun) {
+    const elapsed = formatDuration(state.activeRun.startedAt, now.toISOString());
+    const startTime = new Date(state.activeRun.startedAt).toLocaleString("zh-CN", {
+      timeZone: "Asia/Shanghai",
+      month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit"
+    });
+    lines.push(`当前:  🔧 处理 issue #${state.activeRun.issueIid}`);
+    lines.push(`分支:  ${state.activeRun.branch}`);
+    lines.push(`耗时:  ${elapsed}`);
+    lines.push(`开始:  ${startTime}`);
+  } else {
+    lines.push(`当前:  💤 空闲`);
+  }
+
+  if (state.lastRun) {
+    const icon = state.lastRun.status === "completed" ? "✅"
+      : state.lastRun.status === "failed" ? "❌" : "⏸️";
+    const ago = formatDuration(state.lastRun.at, now.toISOString());
+    const summary = state.lastRun.summary?.slice(0, 60) ?? "";
+    lines.push(`\n上次: ${icon} #${state.lastRun.issueIid ?? "?"} ${summary} — ${ago}前`);
+  }
+
+  const history = state.runHistory ?? [];
+  if (history.length > 0) {
+    lines.push("\n" + "\u2501".repeat(50));
+    const count = Math.min(5, history.length);
+    lines.push(`\n最近 ${count} 条历史:`);
+    const recent = history.slice(-5).reverse();
+    for (const e of recent) {
+      const eIcon = e.status === "completed" ? "✅" : "❌";
+      const dur = formatDuration(e.startedAt, e.finishedAt);
+      const title = e.issueTitle ? ` ${e.issueTitle.slice(0, 30)}` : "";
+      lines.push(`  ${eIcon} #${e.issueIid}  ${e.status.padEnd(10)} ${dur.padEnd(8)} ${e.branch ?? "-"}${title}`);
+    }
+  }
+
+  const timeStr = now.toLocaleTimeString("zh-CN", { timeZone: "Asia/Shanghai" });
+  lines.push(`\n刷新于 ${timeStr} (每 5s)`);
+
+  return lines.join("\n");
+}
+
+async function cmdWatch(name: string): Promise<void> {
+  await loadAgentByName(AGENTS_DIR, name);
+
+  const refresh = async () => {
+    process.stdout.write("\x1B[2J\x1B[H");
+    const status = await getAgentStatus(PROJECT_DIR, name);
+    const store = new FileStateStore(agentStatePath(PROJECT_DIR, name));
+    const state = await store.load();
+    console.log(renderWatchScreen(name, status, state, new Date()));
+  };
+
+  await refresh();
+  const interval = setInterval(refresh, 5000);
+
+  process.on("SIGINT", () => {
+    clearInterval(interval);
+    console.log("\n再见。");
+    process.exit(0);
+  });
+
+  await new Promise(() => {});
+}
+
+// ── Retry command ──────────────────────────────────────────────────────────
+
+export interface RetryDependencies {
+  stateStore: { load(): Promise<import("./state-store.js").LocalAgentState>; save(state: import("./state-store.js").LocalAgentState): Promise<void> };
+  gitlabClient: Pick<import("./gitlab-glab-client.js").GitlabClient, "getIssue" | "updateIssueLabels" | "addIssueNote">;
+  projectId: number;
+  isPidAlive: (pid: number) => boolean;
+  /** Check if a worktree path exists on disk */
+  worktreeExists?: (worktreePath: string) => Promise<boolean>;
+}
+
+export interface RetryResult {
+  status: "retried" | "busy" | "not_error";
+  message: string;
+  /** When resume=true and worktree exists, this is the preserved worktree path */
+  resumeWorktree?: string;
+}
+
+export async function retryIssue(
+  name: string,
+  issueIid: number,
+  deps: RetryDependencies,
+  options?: { resume?: boolean }
+): Promise<RetryResult> {
+  const { stateStore, gitlabClient, projectId, isPidAlive: checkPid } = deps;
+  const resume = options?.resume ?? false;
+
+  // 1. Load state
+  const state = await stateStore.load();
+
+  // 2. Check if agent is busy
+  if (state.activeRun && checkPid(state.activeRun.pid)) {
+    return {
+      status: "busy",
+      message:
+        `Agent "${name}" is busy processing issue #${state.activeRun.issueIid} (PID ${state.activeRun.pid}).` +
+        `\nPlease wait for the current run to finish before retrying.`
+    };
+  }
+
+  // 3. Fetch issue from GitLab
+  const issue = await gitlabClient.getIssue(projectId, issueIid);
+
+  // 4. Verify issue is in Error state
+  if (!issue.labels.includes("Error")) {
+    return {
+      status: "not_error",
+      message:
+        `Issue #${issueIid} is not in Error state (current labels: ${issue.labels.join(", ")}).` +
+        `\nOnly issues with the "Error" label can be retried.`
+    };
+  }
+
+  // 5. Check for existing worktree if --resume
+  let resumeWorktree: string | undefined;
+  if (resume) {
+    // Look for worktree path in last run history for this issue
+    const historyEntry = state.runHistory?.slice().reverse().find(e => e.issueIid === issueIid);
+    const lastRunWorktree = state.lastRun?.issueIid === issueIid ? state.lastRun.worktreePath : undefined;
+    const candidatePath = lastRunWorktree ?? historyEntry?.branch;
+
+    // Also check the conventional worktree path
+    const worktreeRoot = agentWorktreeRoot(PROJECT_DIR, name);
+    const { worktreePathForIssue } = await import("./worktree-manager.js");
+    const conventionalPath = worktreePathForIssue(worktreeRoot, issueIid, issue.title);
+
+    if (deps.worktreeExists) {
+      if (lastRunWorktree && await deps.worktreeExists(lastRunWorktree)) {
+        resumeWorktree = lastRunWorktree;
+      } else if (await deps.worktreeExists(conventionalPath)) {
+        resumeWorktree = conventionalPath;
+      }
+    }
+  }
+
+  // 6. Remove issue from processedIssueIds
+  state.processedIssueIds = state.processedIssueIds.filter((id) => id !== issue.id);
+
+  // 7. Clear notifiedBusyTodoIds so the agent does not skip re-notifications
+  state.notifiedBusyTodoIds = [];
+
+  // 8. Save state
+  await stateStore.save(state);
+
+  // 9. Transition labels from Error to Todo
+  const newLabels = transitionStatusLabels(issue.labels, "Todo");
+  await gitlabClient.updateIssueLabels(projectId, issueIid, newLabels);
+
+  // 10. Add note on issue
+  const noteText = resumeWorktree
+    ? "🔄 已重置为待处理（恢复模式），agent 将在现有 worktree 上继续工作。"
+    : "🔄 已重置为待处理，等待 agent 下一轮接单。";
+  await gitlabClient.addIssueNote(projectId, issueIid, noteText);
+
+  const resumeInfo = resumeWorktree ? `\n  Resume: worktree preserved at ${resumeWorktree}` : "";
+
+  return {
+    status: "retried",
+    message:
+      `Retried issue #${issueIid} for agent "${name}".\n` +
+      `  Labels: ${issue.labels.join(", ")} → ${newLabels.join(", ")}\n` +
+      `  Issue removed from processedIssueIds.\n` +
+      `  Agent will pick it up in the next poll cycle.` + resumeInfo,
+    resumeWorktree
+  };
+}
+
+async function cmdRetry(name: string, issueIid: number, resume?: boolean): Promise<void> {
+  const agentDef = await loadAgentByName(AGENTS_DIR, name);
+  const config = loadConfigFromAgentDefinition(agentDef, process.env, { cwd: PROJECT_DIR });
+
+  const store = new FileStateStore(agentStatePath(PROJECT_DIR, name));
+  const client = new GitlabGlabClient({
+    host: config.gitlabHost,
+    token: config.gitlabToken
+  });
+
+  const { isPidAlive } = await import("./process-manager.js");
+  const { stat: fsStat } = await import("node:fs/promises");
+  const worktreeExists = async (p: string) => {
+    try { await fsStat(p); return true; } catch { return false; }
+  };
+
+  const result = await retryIssue(name, issueIid, {
+    stateStore: store,
+    gitlabClient: client,
+    projectId: config.gitlabProjectId!,
+    isPidAlive,
+    worktreeExists
+  }, { resume });
+
+  if (result.status === "retried") {
+    console.log(result.message);
+  } else {
+    console.error(result.message);
+    process.exit(1);
+  }
+}
+
+// ── Why command ───────────────────────────────────────────────────────────
+
+export interface WhyDiagnosticResult {
+  agent: string;
+  reason: string;
+  icon: "pass" | "fail" | "warn" | "busy";
+}
+
+export interface WhyDependencies {
+  getAgentStatus: (repoPath: string, agentName: string) => Promise<{ alive: boolean; pid?: number }>;
+  loadState: (statePath: string) => Promise<import("./state-store.js").LocalAgentState>;
+  getIssue: (host: string, token: string, projectId: number, issueIid: number) => Promise<import("./gitlab-glab-client.js").GitlabIssue>;
+  getIssueNotes: (host: string, token: string, projectId: number, issueIid: number) => Promise<import("./gitlab-glab-client.js").GitlabNote[]>;
+  listTodos: (host: string, token: string, projectId: number) => Promise<import("./gitlab-glab-client.js").GitlabTodoItem[]>;
+  env: NodeJS.ProcessEnv;
+}
+
+export async function diagnoseIssue(
+  issueIid: number,
+  agents: import("./agent-config.js").AgentDefinition[],
+  projectDir: string,
+  deps: WhyDependencies
+): Promise<WhyDiagnosticResult[]> {
+  const results: WhyDiagnosticResult[] = [];
+
+  for (const agent of agents) {
+    const status = await deps.getAgentStatus(projectDir, agent.name);
+    if (!status.alive) {
+      results.push({ agent: agent.name, icon: "fail", reason: `Agent 未运行。运行 'pnpm agent start ${agent.name}' 启动。` });
+      continue;
+    }
+
+    const token = deps.env[agent.gitlab.token_env];
+    if (!token) {
+      results.push({ agent: agent.name, icon: "fail", reason: `Token ${agent.gitlab.token_env} 未设置。` });
+      continue;
+    }
+
+    let config;
+    try {
+      config = loadConfigFromAgentDefinition(agent, deps.env, { cwd: projectDir });
+    } catch (err) {
+      results.push({ agent: agent.name, icon: "fail", reason: `配置加载失败: ${String(err)}` });
+      continue;
+    }
+
+    const state = await deps.loadState(agentStatePath(projectDir, agent.name));
+
+    if (state.activeRun) {
+      results.push({ agent: agent.name, icon: "busy", reason: `Agent 正忙，正在处理 issue #${state.activeRun.issueIid}。` });
+      continue;
+    }
+
+    let issue;
+    try {
+      issue = await deps.getIssue(config.gitlabHost, config.gitlabToken, config.gitlabProjectId!, issueIid);
+    } catch {
+      results.push({ agent: agent.name, icon: "fail", reason: `无法获取 issue #${issueIid}（可能不属于此 agent 的项目）。` });
+      continue;
+    }
+
+    if (state.processedIssueIds.includes(issue.id)) {
+      if (issue.labels.includes("Error")) {
+        results.push({ agent: agent.name, icon: "warn", reason: `Issue 已处理过且处于 Error 状态。Agent 会在下一轮重新接单（re-trigger 机制）。` });
+      } else {
+        results.push({ agent: agent.name, icon: "fail", reason: `Issue 已在 processedIssueIds 中。用 'pnpm agent retry ${agent.name} ${issueIid}' 重置。` });
+      }
+      continue;
+    }
+
+    const triggers = agent.triggers;
+    if (triggers.labels.length > 0) {
+      const missing = triggers.labels.filter(l => !issue.labels.includes(l));
+      if (missing.length > 0) {
+        results.push({ agent: agent.name, icon: "fail", reason: `Issue 缺少必要 label: ${missing.join(", ")}（agent 要求: ${triggers.labels.join(", ")}）` });
+        continue;
+      }
+    }
+    if (triggers.exclude_labels.length > 0) {
+      const excluded = triggers.exclude_labels.filter(l => issue.labels.includes(l));
+      if (excluded.length > 0) {
+        results.push({ agent: agent.name, icon: "fail", reason: `Issue 包含排除 label: ${excluded.join(", ")}` });
+        continue;
+      }
+    }
+
+    try {
+      const notes = await deps.getIssueNotes(config.gitlabHost, config.gitlabToken, config.gitlabProjectId!, issueIid);
+      const accepted = notes.some(n => !n.system && /^(Claude Code|Codex) 已接单。/.test(n.body));
+      if (accepted) {
+        results.push({ agent: agent.name, icon: "fail", reason: `Issue 已被其他 agent 接走（发现 "已接单" note）。` });
+        continue;
+      }
+    } catch { /* ignore */ }
+
+    try {
+      const todos = await deps.listTodos(config.gitlabHost, config.gitlabToken, config.gitlabProjectId!);
+      const hasTodo = todos.some(t => t.issueIid === issueIid && t.state === "pending");
+      if (!hasTodo) {
+        results.push({ agent: agent.name, icon: "fail", reason: `没有对应的 pending todo。请确认是否已在 issue 中 @mention bot。` });
+        continue;
+      }
+    } catch { /* ignore */ }
+
+    results.push({ agent: agent.name, icon: "pass", reason: `一切正常。Agent 应该会在下一轮轮询时处理此 issue。` });
+  }
+
+  return results;
+}
+
+async function cmdWhy(issueIid: number): Promise<void> {
+  const agents = await discoverAgents(AGENTS_DIR);
+  if (agents.length === 0) {
+    console.log("❌ 没有发现任何 agent 定义。");
+    return;
+  }
+
+  console.log(`诊断 issue #${issueIid} 未被接单的原因...\n`);
+
+  const icons = { pass: "✅", fail: "❌", warn: "⚠️ ", busy: "⏳" };
+  const deps: WhyDependencies = {
+    getAgentStatus: (rp, n) => getAgentStatus(rp, n),
+    loadState: (sp) => new FileStateStore(sp).load(),
+    getIssue: (h, t, p, i) => new GitlabGlabClient({ host: h, token: t }).getIssue(p, i),
+    getIssueNotes: (h, t, p, i) => new GitlabGlabClient({ host: h, token: t }).getIssueNotes(p, i),
+    listTodos: (h, t, p) => new GitlabGlabClient({ host: h, token: t }).listMentionedIssueTodos(p),
+    env: process.env
+  };
+
+  const results = await diagnoseIssue(issueIid, agents, PROJECT_DIR, deps);
+  for (const r of results) {
+    console.log(`── Agent: ${r.agent} ──`);
+    console.log(`  ${icons[r.icon]} ${r.reason}`);
+  }
+}
+
+// ── Sweep command ────────────────────────────────────────────────────────
+
+export interface SweepDependencies {
+  gitlabClient: Pick<import("./gitlab-glab-client.js").GitlabClient, "listClosedIssuesByLabel" | "updateIssueLabels" | "addIssueNote">;
+  projectId: number;
+  logger?: Pick<typeof console, "log">;
+}
+
+export interface SweepResult {
+  transitioned: number;
+  skipped: number;
+}
+
+export async function sweepMergedIssues(deps: SweepDependencies): Promise<SweepResult> {
+  const { gitlabClient, projectId, logger } = deps;
+  const closed = await gitlabClient.listClosedIssuesByLabel(projectId, "In Review");
+  let transitioned = 0;
+  let skipped = 0;
+  for (const issue of closed) {
+    if (issue.stateReason !== "merged") {
+      logger?.log(`  跳过 #${issue.iid} "${issue.title}" (关闭原因: ${issue.stateReason ?? "unknown"})`);
+      skipped++;
+      continue;
+    }
+    await gitlabClient.updateIssueLabels(projectId, issue.iid, transitionStatusLabels(issue.labels, "Done"));
+    await gitlabClient.addIssueNote(projectId, issue.iid, "🏁 MR 已合并，issue 自动流转到 Done。");
+    logger?.log(`  ✅ #${issue.iid} "${issue.title}" → Done`);
+    transitioned++;
+  }
+  return { transitioned, skipped };
+}
+
+// ── GC command ────────────────────────────────────────────────────────────
+
+export interface GcDependencies {
+  gitlabClient: Pick<import("./gitlab-glab-client.js").GitlabClient, "getIssue">;
+  projectId: number;
+  worktreeRoot: string;
+  repoPath: string;
+  activeWorktreePaths: string[];
+  listWorktreeDirs: () => Promise<string[]>;
+  removeWorktree: (worktreePath: string) => Promise<void>;
+  logger?: Pick<typeof console, "log">;
+}
+
+export interface GcResult {
+  removed: number;
+  skipped: number;
+  errors: number;
+}
+
+export async function gcWorktrees(deps: GcDependencies): Promise<GcResult> {
+  const { gitlabClient, projectId, worktreeRoot, activeWorktreePaths, listWorktreeDirs, removeWorktree, logger } = deps;
+
+  let removed = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  let dirs: string[];
+  try {
+    dirs = await listWorktreeDirs();
+  } catch {
+    return { removed, skipped, errors };
+  }
+
+  for (const dir of dirs) {
+    const match = dir.match(/^issue-(\d+)-/);
+    if (!match) {
+      logger?.log(`  跳过 ${dir} (无法解析 issue IID)`);
+      skipped++;
+      continue;
+    }
+
+    const issueIid = Number.parseInt(match[1], 10);
+    const worktreePath = path.join(worktreeRoot, dir);
+
+    if (activeWorktreePaths.includes(worktreePath)) {
+      logger?.log(`  跳过 ${dir} (active run)`);
+      skipped++;
+      continue;
+    }
+
+    let issue: import("./gitlab-glab-client.js").GitlabIssue;
+    try {
+      issue = await gitlabClient.getIssue(projectId, issueIid);
+    } catch {
+      logger?.log(`  跳过 ${dir} (无法获取 issue #${issueIid})`);
+      skipped++;
+      continue;
+    }
+
+    if (issue.state !== "closed") {
+      logger?.log(`  跳过 ${dir} (issue #${issueIid} 仍开放)`);
+      skipped++;
+      continue;
+    }
+
+    try {
+      await removeWorktree(worktreePath);
+      logger?.log(`  ✅ 删除 ${dir} (issue #${issueIid} 已关闭)`);
+      removed++;
+    } catch (err) {
+      logger?.log(`  ❌ 删除 ${dir} 失败: ${String(err)}`);
+      errors++;
+    }
+  }
+
+  return { removed, skipped, errors };
+}
+
+async function cmdGc(nameOrAll: string): Promise<void> {
+  const { readdir } = await import("node:fs/promises");
+
+  const runGc = async (agentName: string): Promise<GcResult> => {
+    const agent = await loadAgentByName(AGENTS_DIR, agentName);
+    const config = loadConfigFromAgentDefinition(agent, process.env, { cwd: PROJECT_DIR });
+    const client = new GitlabGlabClient({ host: config.gitlabHost, token: config.gitlabToken });
+
+    const worktreeRoot = agentWorktreeRoot(PROJECT_DIR, agentName);
+    const store = new FileStateStore(agentStatePath(PROJECT_DIR, agentName));
+    const state = await store.load();
+    const activeWorktreePaths = state.activeRun ? [state.activeRun.worktreePath] : [];
+
+    return gcWorktrees({
+      gitlabClient: client,
+      projectId: config.gitlabProjectId!,
+      worktreeRoot,
+      repoPath: config.agentRepoPath,
+      activeWorktreePaths,
+      listWorktreeDirs: async () => {
+        const entries = await readdir(worktreeRoot, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+      },
+      removeWorktree: async (worktreePath: string) => {
+        await execFileAsync("git", ["-C", config.agentRepoPath, "worktree", "remove", "--force", worktreePath]);
+      },
+      logger: console
+    });
+  };
+
+  if (nameOrAll === "--all") {
+    const agents = await discoverAgents(AGENTS_DIR);
+    let totalRemoved = 0;
+    for (const agent of agents) {
+      console.log(`GC for ${agent.name}...`);
+      const result = await runGc(agent.name);
+      totalRemoved += result.removed;
+    }
+    console.log(`\n共清理 ${totalRemoved} 个 worktree。`);
+  } else {
+    console.log(`GC for ${nameOrAll}...`);
+    const result = await runGc(nameOrAll);
+    console.log(`\n已清理 ${result.removed} 个 worktree，跳过 ${result.skipped} 个，错误 ${result.errors} 个。`);
+  }
+}
+
+async function cmdSweep(nameOrAll: string): Promise<void> {
+  const runSweep = async (agentName: string): Promise<number> => {
+    const agent = await loadAgentByName(AGENTS_DIR, agentName);
+    const config = loadConfigFromAgentDefinition(agent, process.env, { cwd: PROJECT_DIR });
+    const client = new GitlabGlabClient({ host: config.gitlabHost, token: config.gitlabToken });
+    const result = await sweepMergedIssues({ gitlabClient: client, projectId: config.gitlabProjectId!, logger: console });
+    return result.transitioned;
+  };
+
+  if (nameOrAll === "--all") {
+    const agents = await discoverAgents(AGENTS_DIR);
+    const seen = new Set<string>();
+    let total = 0;
+    for (const agent of agents) {
+      const key = `${agent.gitlab.host ?? ""}:${agent.gitlab.project_id ?? ""}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      console.log(`Sweeping for ${agent.name}...`);
+      total += await runSweep(agent.name);
+    }
+    console.log(`\n共 ${total} 个 issue 从 In Review 流转到 Done。`);
+    if (total > 0) await sendNotification({ title: "glab-agent sweep", message: `${total} issue(s) moved to Done` });
+  } else {
+    console.log(`Sweeping for ${nameOrAll}...`);
+    const count = await runSweep(nameOrAll);
+    console.log(`\n共 ${count} 个 issue 从 In Review 流转到 Done。`);
+    if (count > 0) await sendNotification({ title: "glab-agent sweep", message: `${count} issue(s) moved to Done` });
+  }
+}
+
+// ── Wiki command ──────────────────────────────────────────────────────────
+
+async function cmdWiki(args: string[]): Promise<void> {
+  const subcommand = args[0];
+  if (!subcommand || subcommand === "help" || subcommand === "--help") {
+    console.log("Usage: glab-agent wiki <command>\n");
+    console.log("Commands:");
+    console.log("  init    Initialize Knowledge Wiki directory structure");
+    return;
+  }
+
+  if (subcommand === "init") {
+    const repoRoot = process.cwd();
+    await initWikiDir(repoRoot);
+    const dir = wikiPath(repoRoot);
+    console.log(`✅ Knowledge Wiki initialized at ${dir}`);
+    console.log("   Created: index.md, log.md, patterns/, gotchas/, decisions/, runbooks/");
+    return;
+  }
+
+  console.error(`Unknown wiki command: ${subcommand}`);
+  process.exit(1);
+}
+
+async function main(): Promise<void> {
+  const args = stripProjectFlag(process.argv.slice(2));
+  const command = args[0];
+  const target = args[1];
+
+  switch (command) {
+    case "init": {
+      const initProvider = extractFlag(args, "--provider");
+      const initLabels = extractFlag(args, "--labels");
+      const initTokenEnv = extractFlag(args, "--token-env");
+      await cmdInit(target, { provider: initProvider, labels: initLabels, tokenEnv: initTokenEnv });
+      break;
+    }
+    case "list":
+      await cmdList();
+      break;
+    case "start":
+      if (!target) { console.error("Usage: pnpm agent start <name|--all>"); process.exit(1); }
+      await cmdStart(target);
+      break;
+    case "stop":
+      if (!target) { console.error("Usage: pnpm agent stop <name|--all>"); process.exit(1); }
+      await cmdStop(target);
+      break;
+    case "cancel":
+      if (!target) { console.error("Usage: pnpm agent cancel <name>"); process.exit(1); }
+      await cmdCancel(target);
+      break;
+    case "retry": {
+      if (!target) { console.error("Usage: pnpm agent retry <name> <iid> [--resume]"); process.exit(1); }
+      const iid = Number.parseInt(args[2], 10);
+      if (Number.isNaN(iid)) { console.error("issue iid must be a number"); process.exit(1); }
+      const resume = args.includes("--resume");
+      await cmdRetry(target, iid, resume);
+      break;
+    }
+    case "why": {
+      if (!target) { console.error("Usage: pnpm agent why <issue-iid>"); process.exit(1); }
+      const iid = Number.parseInt(target, 10);
+      if (Number.isNaN(iid)) { console.error("issue-iid 必须是数字"); process.exit(1); }
+      await cmdWhy(iid);
+      break;
+    }
+    case "status":
+      await cmdStatus(target);
+      break;
+    case "logs":
+      if (!target) { console.error("Usage: pnpm agent logs <name>"); process.exit(1); }
+      await cmdLogs(target);
+      break;
+    case "run-once":
+      if (!target) { console.error("Usage: pnpm agent run-once <name>"); process.exit(1); }
+      await cmdRunOnce(target);
+      break;
+    case "watch":
+      if (!target) { console.error("Usage: pnpm agent watch <name>"); process.exit(1); }
+      await cmdWatch(target);
+      break;
+    case "history": {
+      if (!target) { console.error("Usage: pnpm agent history <name> [--last N]"); process.exit(1); }
+      const lastIdx = args.indexOf("--last");
+      const last = lastIdx !== -1 && args[lastIdx + 1] ? Number.parseInt(args[lastIdx + 1], 10) : 20;
+      await cmdHistory(target, Number.isNaN(last) || last <= 0 ? 20 : last);
+      break;
+    }
+    case "report": {
+      if (!target) { console.error("Usage: pnpm agent report <name> [--since <N>d]"); process.exit(1); }
+      const sinceIdx = args.indexOf("--since");
+      let sinceDays = 7;
+      if (sinceIdx !== -1 && args[sinceIdx + 1]) {
+        const match = args[sinceIdx + 1].match(/^(\d+)d$/);
+        if (match) sinceDays = Number.parseInt(match[1], 10);
+      }
+      await cmdReport(target, sinceDays);
+      break;
+    }
+    case "sweep":
+      if (!target) { console.error("Usage: pnpm agent sweep <name|--all>"); process.exit(1); }
+      await cmdSweep(target);
+      break;
+    case "gc":
+      if (!target) { console.error("Usage: pnpm agent gc <name|--all>"); process.exit(1); }
+      await cmdGc(target);
+      break;
+    case "install":
+      if (!target) { console.error("Usage: pnpm agent install <name|--all>"); process.exit(1); }
+      await cmdInstall(target);
+      break;
+    case "skills":
+      if (target === "import") {
+        const importTarget = args[2];
+        if (!importTarget) { console.error("Usage: pnpm agent skills import <github-url|owner/repo> [--force]"); process.exit(1); }
+        const force = args.includes("--force");
+        await cmdSkillImport(importTarget, { force });
+      } else {
+        await cmdSkills();
+      }
+      break;
+    case "wiki":
+      await cmdWiki(args.slice(1));
+      break;
+    case "doctor":
+      await cmdDoctor();
+      break;
+    default:
+      usage();
+      break;
+  }
+}
+
+main().catch((error) => {
+  console.error(String(error));
+  process.exit(1);
+});