claude-task-worker 0.10.0 → 0.12.0

package/README.md

@@ -60,6 +60,10 @@ GitHub Issues/PRを定期ポーリングし、Claude Codeに処理を委譲す
 
 `epic-issue` ワーカーは、`cc-epic-issue` ラベル付きの親Issueに紐づくサブIssueがすべて Close されたタイミングで `/claude-task-worker:create-epic-pr` を起動し、エピックブランチからまとめてPRを作成する。
 
+### `--project` 指定時（ディスパッチャーモード）
+
+`--project` オプションを指定した場合、CLIは自身でワーカーを起動する代わりに [herdr](https://herdr.dev) 経由のディスパッチャーとして動作する。指定したプロジェクトごとにherdrのタブ（ペイン）を作成し、そのプロジェクトのディレクトリで（`--project` を除いた）同じコマンドを非同期実行させ、稼働状況をステータステーブルで監視する。詳細は「[`--project <name>` オプション](#--project-name-オプション)」を参照。
+
 ## 必要なライブラリ
 
 ### 実行時に必要なもの
@@ -68,12 +72,13 @@ CLI 本体に npm の実行時依存パッケージはない（ビルド時に e
 
 | 名前 | バージョン | 用途 |
 |---|---|---|
-| [Node.js](https://nodejs.org/) | >= 20 | CLI の実行ランタイム |
+| [Node.js](https://nodejs.org/) | >= 22.6.0 | CLI の実行ランタイム（`--experimental-strip-types` を使用するテスト実行に必要） |
 | [GitHub CLI (`gh`)](https://cli.github.com/) | - | Issue/PR の取得・ラベル操作など全GitHub操作（認証済みであること） |
 | [Claude Code (`claude`)](https://docs.anthropic.com/en/docs/claude-code) | - | タスク実行エンジン。各ワーカーが Claude CLI プロセスとして起動する |
 | [Git (`git`)](https://git-scm.com/) | - | worktree の作成・ブランチ操作 |
 | [jq](https://jqlang.org/) | - | プラグインスキル内でのJSON加工（`check-dependabot` / `edit-pencil-design` スキルなどで使用） |
 | [Pencil CLI (`pencil`)](https://docs.pencil.dev/for-developers/pencil-cli) | - | `.pen` デザインファイルの編集・参照・コンフリクト解消（`edit-pencil-design` / `inspect-pencil-node` / `resolve-pencil-conflict` スキルで使用） |
+| [herdr](https://herdr.dev) | - | `--project` 使用時にのみ必要（通常ワーカー実行には不要）。複数プロジェクトへのディスパッチ・セッション監視・一括停止に使用 |
 | `claude-task-worker` プラグイン | - | 各ワーカーが呼び出すスキル群（本リポジトリの `plugin/`） |
 
 Slack通知（任意）を使う場合は Slack Incoming Webhook URL が必要。Claude API使用状況の取得には、macOSでは `security` コマンド（Keychain）を使用し、それ以外の環境では `~/.claude/.credentials.json` にフォールバックする。
@@ -105,10 +110,11 @@ Slack通知（任意）を使う場合は Slack Incoming Webhook URL が必要
 
 ### 前提条件
 
-- [Node.js](https://nodejs.org/) v20 以上がインストール済みであること
+- [Node.js](https://nodejs.org/) v22.6 以上がインストール済みであること
 - [GitHub CLI (`gh`)](https://cli.github.com/) がインストール・認証済みであること
 - [Claude Code (`claude`)](https://docs.anthropic.com/en/docs/claude-code) がインストール済みであること
 - `claude-task-worker` プラグインがインストール済みであること（下記インストール手順を参照）
+- `--project` オプションを使う場合のみ、[herdr](https://herdr.dev) がインストール済みであること（通常のワーカー実行には不要）
 
 詳細は上記「[必要なライブラリ](#必要なライブラリ)」を参照。
 
@@ -155,6 +161,16 @@ claude plugin install claude-task-worker@claude-task-worker
 
 インストール後、Claude Code のセッションを再起動するとプラグインが有効化される。
 
+herdr（`--project` オプションを使う場合のみ必要。通常ワーカー実行には不要）:
+
+```bash
+curl -fsSL https://herdr.dev/install.sh | sh
+# または
+brew install herdr
+```
+
+詳細は [herdr インストールドキュメント](https://herdr.dev/docs/install/) を参照。
+
 #### 更新
 
 CLI とプラグイン（マーケットプレイス）をまとめて更新する。
@@ -232,6 +248,49 @@ claude-task-worker yolo --epic 100 --epic 200 --label priority-high
 
 > ℹ️ `--label` で指定したラベルはユーザーのスコープ指定なので、タスク完了時にワーカー側で除去されることはない（トリガーラベルだけが除去される）。
 
+### `--project <name>` オプション
+
+指定したプロジェクト（またはプロジェクトグループ、`all`）に対して、[herdr](https://herdr.dev) 経由でコマンドをディスパッチする。指定すると、CLIはワーカーをその場で実行する代わりにディスパッチャーとして動作し、対象プロジェクトごとに独立したherdrタブでコマンドを実行する。
+
+プロジェクト名・グループ名・`all` のいずれかを指定できる。
+
+- プロジェクト名: `projects.json` の `projects` に登録された個別プロジェクト名
+- グループ名: `projects.json` の `projectGroups` に登録された、複数プロジェクト名をまとめたグループ名
+- `all`: `projects.json` の `projects` に登録された全プロジェクトが対象になる予約語（`projects` / `projectGroups` のキーとして使用不可）
+
+`projects.json` は `$XDG_CONFIG_HOME/claude-task-worker/projects.json`（`XDG_CONFIG_HOME` 未設定の場合は `~/.config/claude-task-worker/projects.json`）に配置する。`projects` にプロジェクト名から絶対パスへのマッピングを、`projectGroups` にグループ名からプロジェクト名配列へのマッピングを記述する（`projectGroups` は省略可）。
+
+```json
+{
+  "projects": {
+    "app-a": "/Users/me/repos/app-a",
+    "app-b": "/Users/me/repos/app-b",
+    "app-c": "/Users/me/repos/app-c"
+  },
+  "projectGroups": {
+    "frontend": ["app-a", "app-b"]
+  }
+}
+```
+
+`--project` は繰り返し指定可能で、複数指定した場合は解決後のプロジェクト集合の和集合が対象になる（重複は一意化される）。`--epic` / `--label` と併用でき、ディスパッチ先の各プロジェクトで実行されるコマンドにそのまま引き継がれる。
+
+以下のコマンドは `--project` と併用できない: `init` / `install` / `update` / `usage` / `version`
+
+ディスパッチャーは以下の3つの機能を持つ。
+
+- **一斉起動**: 対象プロジェクトごとにherdrタブを作成し、そのプロジェクトのディレクトリで（`--project` を除いた）同じコマンドを非同期実行する
+- **稼働一覧**: 各セッションのプロジェクト名・タブID・ペインID・ステータス・稼働時間をステータステーブルとして定期的に画面へ描画し、対象プロセスが終了したセッションは自動的に一覧から除去する
+- **一括停止**: SIGTERM/SIGINTを受けると、稼働中の全セッションへ ctrl-c を送信して各プロジェクトのコマンドを終了させ、終了を待ってからherdrタブを閉じる
+
+```bash
+claude-task-worker all --project all
+claude-task-worker all --project app-a
+claude-task-worker all --project frontend
+claude-task-worker all --project app-a --project app-c    # app-a と app-c の和集合
+claude-task-worker exec-issue --project app-a --epic 100 --label priority-high
+```
+
 ### exec-issue
 
 `cc-exec-issue` ラベルが付いた自分にアサインされたIssueを定期取得し、Claude Codeで処理を実行する。（デフォルト1分間隔）

package/dist/index.js

@@ -1,4 +1,451 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/table.ts
+var table_exports = {};
+__export(table_exports, {
+  getDisplayWidth: () => getDisplayWidth,
+  padToWidth: () => padToWidth,
+  truncateToWidth: () => truncateToWidth
+});
+function getDisplayWidth(str) {
+  let width = 0;
+  for (const char of str) {
+    const code = char.codePointAt(0);
+    if (code >= 4352 && code <= 4447 || code >= 11904 && code <= 12350 || code >= 12352 && code <= 13247 || code >= 13312 && code <= 19903 || code >= 19968 && code <= 42191 || code >= 44032 && code <= 55215 || code >= 63744 && code <= 64255 || code >= 65072 && code <= 65135 || code >= 65281 && code <= 65376 || code >= 65504 && code <= 65510 || code >= 131072 && code <= 196605 || code >= 196608 && code <= 262141) {
+      width += 2;
+    } else {
+      width += 1;
+    }
+  }
+  return width;
+}
+function truncateToWidth(str, maxWidth) {
+  let width = 0;
+  let i = 0;
+  const chars = [...str];
+  while (i < chars.length) {
+    const charWidth = getDisplayWidth(chars[i]);
+    if (width + charWidth > maxWidth - 3) {
+      return chars.slice(0, i).join("") + "...";
+    }
+    width += charWidth;
+    i++;
+  }
+  return str;
+}
+function padToWidth(str, targetWidth) {
+  const currentWidth = getDisplayWidth(str);
+  const padding = targetWidth - currentWidth;
+  return padding > 0 ? str + " ".repeat(padding) : str;
+}
+var init_table = __esm({
+  "src/table.ts"() {
+    "use strict";
+  }
+});
+
+// src/herdr.ts
+var herdr_exports = {};
+__export(herdr_exports, {
+  HERDR_TIMEOUT_MS: () => HERDR_TIMEOUT_MS,
+  HerdrError: () => HerdrError,
+  HerdrUnavailableError: () => HerdrUnavailableError,
+  checkHerdrAvailable: () => checkHerdrAvailable,
+  paneProcessInfo: () => paneProcessInfo,
+  paneSendKeys: () => paneSendKeys,
+  paneSendText: () => paneSendText,
+  tabClose: () => tabClose,
+  tabCreate: () => tabCreate,
+  tabList: () => tabList
+});
+import { createRequire } from "node:module";
+function runHerdr(args) {
+  return new Promise((resolve2) => {
+    childProcess.execFile(
+      "herdr",
+      args,
+      { timeout: HERDR_TIMEOUT_MS, killSignal: "SIGKILL" },
+      (error, stdout, stderr) => {
+        let parsed;
+        try {
+          parsed = JSON.parse(stdout);
+        } catch {
+          parsed = void 0;
+        }
+        resolve2({ execError: error, parsed, stdout, stderr });
+      }
+    );
+  });
+}
+async function execHerdr(args, options) {
+  const { execError, parsed, stdout, stderr } = await runHerdr(args);
+  const stderrSuffix = stderr.trim() ? `: ${stderr.trim()}` : "";
+  if (parsed?.error) {
+    throw new HerdrError(
+      `herdr ${args.join(" ")} failed: [${parsed.error.code}] ${parsed.error.message}`,
+      parsed.error.code
+    );
+  }
+  if (execError) {
+    throw new Error(`herdr ${args.join(" ")} failed: ${execError.message}${stderrSuffix}`);
+  }
+  if (!parsed) {
+    if (options?.allowEmptyResult && stdout.trim() === "" && stderr.trim() === "") {
+      return void 0;
+    }
+    throw new Error(`herdr ${args.join(" ")} failed: invalid JSON output${stderrSuffix}`);
+  }
+  return parsed.result;
+}
+async function tabCreate({ label, cwd }) {
+  const result = await execHerdr(["tab", "create", "--label", label, "--cwd", cwd, "--no-focus"]);
+  const paneId = result?.root_pane?.pane_id;
+  const tabId = result?.tab?.tab_id;
+  if (!paneId || !tabId) {
+    throw new Error("Failed to create tab: invalid response structure from herdr");
+  }
+  return { paneId, tabId };
+}
+async function tabClose(tabId) {
+  await execHerdr(["tab", "close", tabId]);
+}
+async function tabList() {
+  const result = await execHerdr(["tab", "list"]);
+  if (!result || !Array.isArray(result.tabs)) {
+    return [];
+  }
+  return result.tabs.map((tab) => ({
+    tabId: tab.tab_id,
+    label: tab.label,
+    workspaceId: tab.workspace_id
+  }));
+}
+async function paneSendText(paneId, text) {
+  await execHerdr(["pane", "send-text", paneId, text], { allowEmptyResult: true });
+}
+async function paneSendKeys(paneId, ...keys) {
+  await execHerdr(["pane", "send-keys", paneId, ...keys], { allowEmptyResult: true });
+}
+async function paneProcessInfo(paneId) {
+  const result = await execHerdr(["pane", "process-info", "--pane", paneId]);
+  const foregroundProcesses = result?.process_info?.foreground_processes ?? [];
+  return {
+    foregroundProcesses: foregroundProcesses.map((process2) => ({
+      name: process2.name,
+      argv: process2.argv,
+      cmdline: process2.cmdline,
+      pid: process2.pid
+    }))
+  };
+}
+async function checkHerdrAvailable() {
+  const { execError, parsed } = await runHerdr(["tab", "list"]);
+  if (execError?.code === "ENOENT") {
+    throw new HerdrUnavailableError(
+      "herdr\u304C\u30A4\u30F3\u30B9\u30C8\u30FC\u30EB\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002herdr CLI\u3092\u30A4\u30F3\u30B9\u30C8\u30FC\u30EB\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+      "not-installed"
+    );
+  }
+  if (!parsed) {
+    throw new HerdrUnavailableError(
+      "herdr\u30B5\u30FC\u30D0\u30FC\u306B\u63A5\u7D9A\u3067\u304D\u307E\u305B\u3093\u3067\u3057\u305F\u3002`herdr status` \u7B49\u3067\u8D77\u52D5\u72B6\u614B\u3092\u78BA\u8A8D\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+      "server-unreachable"
+    );
+  }
+}
+var childProcess, HerdrUnavailableError, HerdrError, HERDR_TIMEOUT_MS;
+var init_herdr = __esm({
+  "src/herdr.ts"() {
+    "use strict";
+    childProcess = createRequire(import.meta.url)("node:child_process");
+    HerdrUnavailableError = class extends Error {
+      reason;
+      constructor(message, reason) {
+        super(message);
+        this.name = "HerdrUnavailableError";
+        this.reason = reason;
+      }
+    };
+    HerdrError = class extends Error {
+      code;
+      constructor(message, code) {
+        super(message);
+        this.name = "HerdrError";
+        this.code = code;
+      }
+    };
+    HERDR_TIMEOUT_MS = 15 * 1e3;
+  }
+});
+
+// src/dispatcher.ts
+var dispatcher_exports = {};
+__export(dispatcher_exports, {
+  POLL_INTERVAL_MS: () => POLL_INTERVAL_MS,
+  SHUTDOWN_RETRY_TIMEOUT_MS: () => SHUTDOWN_RETRY_TIMEOUT_MS,
+  SHUTDOWN_TIMEOUT_MS: () => SHUTDOWN_TIMEOUT_MS,
+  formatUptime: () => formatUptime,
+  monitorSessions: () => monitorSessions,
+  pollOnce: () => pollOnce,
+  removeSession: () => removeSession,
+  renderSessionTable: () => renderSessionTable,
+  runDispatcher: () => runDispatcher,
+  shutdownDispatcher: () => shutdownDispatcher
+});
+async function loadHerdr() {
+  return await Promise.resolve().then(() => (init_herdr(), herdr_exports));
+}
+async function loadTable() {
+  return await Promise.resolve().then(() => (init_table(), table_exports));
+}
+async function runDispatcher(projects, forwardedCommand) {
+  const { checkHerdrAvailable: checkHerdrAvailable2, tabCreate: tabCreate2, tabClose: tabClose2, tabList: tabList2, paneSendText: paneSendText2, paneSendKeys: paneSendKeys2 } = await loadHerdr();
+  try {
+    await checkHerdrAvailable2();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[dispatcher] ${message}`);
+    throw error;
+  }
+  const existingTabs = await tabList2();
+  const existingLabels = new Set(existingTabs.map((tab) => tab.label));
+  const sessions = /* @__PURE__ */ new Map();
+  for (const project of projects) {
+    if (existingLabels.has(project.name)) {
+      console.warn(`[dispatcher] project "${project.name}" already has a running tab, skipping`);
+      continue;
+    }
+    let createdTabId;
+    try {
+      const { paneId, tabId } = await tabCreate2({ label: project.name, cwd: project.path });
+      createdTabId = tabId;
+      sessions.set(project.name, {
+        name: project.name,
+        tabId,
+        paneId,
+        startedAt: /* @__PURE__ */ new Date(),
+        status: "running"
+      });
+      await paneSendText2(paneId, forwardedCommand);
+      await paneSendKeys2(paneId, "enter");
+    } catch (error) {
+      console.error(`[dispatcher] failed to dispatch project "${project.name}": ${error}`);
+      sessions.delete(project.name);
+      if (createdTabId !== void 0) {
+        try {
+          await tabClose2(createdTabId);
+        } catch (closeError) {
+          console.error(`[dispatcher] failed to close dangling tab for project "${project.name}": ${closeError}`);
+        }
+      }
+    }
+  }
+  return sessions;
+}
+async function removeSession(sessions, name, { closeTab }) {
+  const session = sessions.get(name);
+  if (!session) return;
+  sessions.delete(name);
+  if (closeTab) {
+    const { tabClose: tabClose2 } = await loadHerdr();
+    await tabClose2(session.tabId);
+  }
+}
+async function pollOnce(sessions, herdr) {
+  for (const [name, session] of [...sessions.entries()]) {
+    try {
+      const { foregroundProcesses } = await herdr.paneProcessInfo(session.paneId);
+      const isAlive = foregroundProcesses.some((process2) => process2.cmdline?.includes("claude-task-worker"));
+      if (!isAlive) {
+        await removeSession(sessions, name, { closeTab: true });
+      }
+    } catch (error) {
+      if (error instanceof herdr.HerdrError && error.code === "pane_not_found") {
+        await removeSession(sessions, name, { closeTab: false });
+        continue;
+      }
+      console.error(`[dispatcher] failed to poll session "${name}": ${error}`);
+    }
+  }
+}
+function formatUptime(start, now) {
+  const totalSeconds = Math.max(0, Math.floor((now.getTime() - start.getTime()) / 1e3));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor(totalSeconds % 3600 / 60);
+  const seconds = totalSeconds % 60;
+  return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+}
+function renderSessionTable(sessions) {
+  const entries = [...sessions.values()];
+  if (entries.length === 0) return;
+  const maxProjectWidth = 20;
+  const rows = entries.map((session) => ({
+    project: getDisplayWidth2(session.name) > maxProjectWidth ? truncateToWidth2(session.name, maxProjectWidth) : session.name,
+    tab: session.tabId,
+    pane: session.paneId,
+    status: session.status,
+    uptime: formatUptime(session.startedAt, /* @__PURE__ */ new Date())
+  }));
+  const colWidths = {
+    project: Math.max(7, ...rows.map((r) => getDisplayWidth2(r.project))),
+    tab: Math.max(3, ...rows.map((r) => r.tab.length)),
+    pane: Math.max(4, ...rows.map((r) => r.pane.length)),
+    status: Math.max(6, ...rows.map((r) => r.status.length)),
+    uptime: Math.max(6, ...rows.map((r) => r.uptime.length))
+  };
+  const cols = [colWidths.project, colWidths.tab, colWidths.pane, colWidths.status, colWidths.uptime];
+  const line = (l, m, r, f) => `${l}${cols.map((w) => f.repeat(w + 2)).join(m)}${r}`;
+  const row = (project, tab, pane, status, uptime) => `\u2502 ${padToWidth2(project, colWidths.project)} \u2502 ${tab.padEnd(colWidths.tab)} \u2502 ${pane.padEnd(colWidths.pane)} \u2502 ${status.padEnd(colWidths.status)} \u2502 ${uptime.padEnd(colWidths.uptime)} \u2502`;
+  const lines = [];
+  lines.push(line("\u250C", "\u252C", "\u2510", "\u2500"));
+  lines.push(row("Project", "Tab", "Pane", "Status", "Uptime"));
+  lines.push(line("\u251C", "\u253C", "\u2524", "\u2500"));
+  for (const r of rows) {
+    lines.push(row(r.project, r.tab, r.pane, r.status, r.uptime));
+  }
+  lines.push(line("\u2514", "\u2534", "\u2518", "\u2500"));
+  console.clear();
+  console.log(lines.join("\n"));
+}
+function monitorSessions(sessions, herdr, options) {
+  const pollIntervalMs = options?.pollIntervalMs ?? POLL_INTERVAL_MS;
+  const renderIntervalMs = options?.renderIntervalMs ?? 1e3;
+  let resolveDone;
+  const done = new Promise((resolve2) => {
+    resolveDone = resolve2;
+  });
+  let settled = false;
+  const finish = () => {
+    if (settled) return;
+    settled = true;
+    clearInterval(pollInterval);
+    clearInterval(renderInterval2);
+    resolveDone();
+  };
+  const pollInterval = setInterval(() => {
+    void pollOnce(sessions, herdr).then(() => {
+      if (sessions.size === 0) {
+        finish();
+      }
+    });
+  }, pollIntervalMs);
+  pollInterval.unref();
+  const renderInterval2 = setInterval(() => {
+    renderSessionTable(sessions);
+  }, renderIntervalMs);
+  renderInterval2.unref();
+  return {
+    stop: finish,
+    done
+  };
+}
+async function sendCtrlCToAllSessions(sessions, herdr) {
+  await Promise.all(
+    [...sessions.values()].map(async (session) => {
+      try {
+        await herdr.paneSendKeys(session.paneId, "ctrl-c");
+      } catch (error) {
+        console.error(`[dispatcher] failed to send ctrl-c to session "${session.name}": ${error}`);
+      }
+    })
+  );
+}
+async function waitUntilSessionsEmpty(sessions, herdr, pollIntervalMs, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (sessions.size > 0) {
+    await pollOnce(sessions, herdr);
+    if (sessions.size === 0) return true;
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve2) => setTimeout(resolve2, pollIntervalMs));
+  }
+  return true;
+}
+async function closeRemainingTabs(sessions, herdr, timeoutMs) {
+  const results = await Promise.all(
+    [...sessions.values()].map(async (session) => {
+      try {
+        await Promise.race([
+          herdr.tabClose(session.tabId),
+          new Promise((_, reject) => {
+            setTimeout(() => reject(new Error("tabClose timed out")), timeoutMs).unref();
+          })
+        ]);
+        return true;
+      } catch (error) {
+        console.error(
+          `[dispatcher] failed to close tab "${session.tabId}" for session "${session.name}" during shutdown: ${error}`
+        );
+        return false;
+      }
+    })
+  );
+  return results.every((closed) => closed);
+}
+async function forceKillAllSessions(sessions, herdr, tabCloseTimeoutMs) {
+  console.log(`[dispatcher] force-kill requested, sending ctrl-c and closing ${sessions.size} session(s) immediately`);
+  await sendCtrlCToAllSessions(sessions, herdr);
+  await closeRemainingTabs(sessions, herdr, tabCloseTimeoutMs);
+  process.exit(1);
+}
+async function shutdownDispatcher(sessions, monitorHandle, options) {
+  if (shutdownPromise) {
+    if (options?.forceKill) {
+      const herdr = options.herdr ?? await loadHerdr();
+      const tabCloseTimeoutMs = options.tabCloseTimeoutMs ?? 5e3;
+      await forceKillAllSessions(sessions, herdr, tabCloseTimeoutMs);
+      return;
+    }
+    console.log("[dispatcher] shutdown already in progress, ignoring duplicate request");
+    return shutdownPromise;
+  }
+  shutdownPromise = (async () => {
+    const herdr = options?.herdr ?? await loadHerdr();
+    const pollIntervalMs = options?.pollIntervalMs ?? POLL_INTERVAL_MS;
+    const shutdownTimeoutMs = options?.shutdownTimeoutMs ?? SHUTDOWN_TIMEOUT_MS;
+    const retryTimeoutMs = options?.retryTimeoutMs ?? SHUTDOWN_RETRY_TIMEOUT_MS;
+    const tabCloseTimeoutMs = options?.tabCloseTimeoutMs ?? 5e3;
+    if (monitorHandle) {
+      monitorHandle.stop();
+      await monitorHandle.done;
+    }
+    console.log(`[dispatcher] shutting down, sending ctrl-c to ${sessions.size} session(s)`);
+    await sendCtrlCToAllSessions(sessions, herdr);
+    let finishedInTime = await waitUntilSessionsEmpty(sessions, herdr, pollIntervalMs, shutdownTimeoutMs);
+    if (!finishedInTime) {
+      console.log(
+        `[dispatcher] ${sessions.size} session(s) still alive after ${shutdownTimeoutMs}ms, resending ctrl-c once`
+      );
+      await sendCtrlCToAllSessions(sessions, herdr);
+      finishedInTime = await waitUntilSessionsEmpty(sessions, herdr, pollIntervalMs, retryTimeoutMs);
+    }
+    const allTabsClosed = await closeRemainingTabs(sessions, herdr, tabCloseTimeoutMs);
+    process.exit(finishedInTime && allTabsClosed ? 0 : 1);
+  })();
+  try {
+    await shutdownPromise;
+  } finally {
+    shutdownPromise = void 0;
+  }
+}
+var getDisplayWidth2, truncateToWidth2, padToWidth2, POLL_INTERVAL_MS, SHUTDOWN_TIMEOUT_MS, SHUTDOWN_RETRY_TIMEOUT_MS, shutdownPromise;
+var init_dispatcher = __esm({
+  async "src/dispatcher.ts"() {
+    "use strict";
+    ({ getDisplayWidth: getDisplayWidth2, truncateToWidth: truncateToWidth2, padToWidth: padToWidth2 } = await loadTable());
+    POLL_INTERVAL_MS = 7 * 1e3;
+    SHUTDOWN_TIMEOUT_MS = 10 * 60 * 1e3;
+    SHUTDOWN_RETRY_TIMEOUT_MS = 90 * 1e3;
+  }
+});
 
 // src/gh.ts
 import { execFile } from "node:child_process";
@@ -460,39 +907,9 @@ async function assertRemoteTrackingExists(epicBranch) {
 
 // src/process-manager.ts
 import { spawn } from "node:child_process";
+init_table();
 var childProcesses = /* @__PURE__ */ new Map();
 var TASK_TIMEOUT_MS = 90 * 60 * 1e3;
-function getDisplayWidth(str) {
-  let width = 0;
-  for (const char of str) {
-    const code = char.codePointAt(0);
-    if (code >= 4352 && code <= 4447 || code >= 11904 && code <= 12350 || code >= 12352 && code <= 13247 || code >= 13312 && code <= 19903 || code >= 19968 && code <= 42191 || code >= 44032 && code <= 55215 || code >= 63744 && code <= 64255 || code >= 65072 && code <= 65135 || code >= 65281 && code <= 65376 || code >= 65504 && code <= 65510 || code >= 131072 && code <= 196605 || code >= 196608 && code <= 262141) {
-      width += 2;
-    } else {
-      width += 1;
-    }
-  }
-  return width;
-}
-function truncateToWidth(str, maxWidth) {
-  let width = 0;
-  let i = 0;
-  const chars = [...str];
-  while (i < chars.length) {
-    const charWidth = getDisplayWidth(chars[i]);
-    if (width + charWidth > maxWidth - 3) {
-      return chars.slice(0, i).join("") + "...";
-    }
-    width += charWidth;
-    i++;
-  }
-  return str;
-}
-function padToWidth(str, targetWidth) {
-  const currentWidth = getDisplayWidth(str);
-  const padding = targetWidth - currentWidth;
-  return padding > 0 ? str + " ".repeat(padding) : str;
-}
 var tasks = /* @__PURE__ */ new Map();
 var shuttingDown = false;
 function setShuttingDown() {
@@ -1842,6 +2259,184 @@ function version() {
   }
 }
 
+// src/dispatch-args.ts
+var PROJECT_INCOMPATIBLE_COMMANDS = ["init", "install", "update", "usage", "version"];
+function collectFlagValues(argv, flag) {
+  const values = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] !== flag) continue;
+    const raw = argv[i + 1];
+    if (!raw || raw.startsWith("--")) {
+      console.error(`[dispatcher] ${flag} requires a value`);
+      process.exit(1);
+    }
+    values.push(raw);
+  }
+  return values;
+}
+function parseProjectFilters() {
+  return collectFlagValues(process.argv, "--project");
+}
+function hasProjectFilter() {
+  return process.argv.includes("--project");
+}
+function assertProjectCompatibleCommand(command) {
+  if (PROJECT_INCOMPATIBLE_COMMANDS.includes(command)) {
+    console.error(`[dispatcher] --project cannot be used with the "${command}" command`);
+    process.exit(1);
+  }
+}
+function shellQuote(value) {
+  if (value === "") return "''";
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function buildForwardedCommand(argv) {
+  const tokens = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--project") {
+      i++;
+      continue;
+    }
+    tokens.push(argv[i]);
+  }
+  return ["claude-task-worker", ...tokens.map(shellQuote)].join(" ");
+}
+
+// src/projects-config.ts
+import { readFileSync as readFileSync4, statSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { isAbsolute, join as join4 } from "node:path";
+var RESERVED_ALL = "all";
+var ProjectsConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ProjectsConfigError";
+  }
+};
+function getProjectsConfigPath() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const configHome = xdg && xdg.length > 0 ? xdg : join4(homedir2(), ".config");
+  return join4(configHome, "claude-task-worker", "projects.json");
+}
+var PROJECTS_CONFIG_PATH = getProjectsConfigPath();
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function loadProjectsConfig() {
+  const configPath = PROJECTS_CONFIG_PATH;
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync4(configPath, "utf-8"));
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new ProjectsConfigError(`projects.json not found: ${configPath}`);
+    }
+    if (err instanceof SyntaxError) {
+      throw new ProjectsConfigError(`projects.json contains invalid JSON: ${configPath}: ${err.message}`);
+    }
+    throw err;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new ProjectsConfigError(`projects.json must contain a JSON object: ${configPath}`);
+  }
+  if (!("projects" in raw) || typeof raw["projects"] !== "object" || raw["projects"] === null || Array.isArray(raw["projects"])) {
+    throw new ProjectsConfigError(`projects.json must contain a "projects" section as an object: ${configPath}`);
+  }
+  if ("projectGroups" in raw && (typeof raw["projectGroups"] !== "object" || raw["projectGroups"] === null || Array.isArray(raw["projectGroups"]))) {
+    throw new ProjectsConfigError(`projects.json "projectGroups" must be an object: ${configPath}`);
+  }
+  const rawProjects = raw["projects"];
+  const rawProjectGroups = "projectGroups" in raw ? raw["projectGroups"] : {};
+  const projectKeys = Object.keys(rawProjects);
+  const groupKeys = Object.keys(rawProjectGroups);
+  if (projectKeys.includes(RESERVED_ALL) || groupKeys.includes(RESERVED_ALL)) {
+    throw new ProjectsConfigError(
+      `"${RESERVED_ALL}" is a reserved word and cannot be used as a key in "projects" or "projectGroups"`
+    );
+  }
+  const groupKeySet = new Set(groupKeys);
+  const duplicateKeys = projectKeys.filter((key) => groupKeySet.has(key));
+  if (duplicateKeys.length > 0) {
+    throw new ProjectsConfigError(
+      `"projects" and "projectGroups" share the same key namespace; duplicate keys are not allowed: ${duplicateKeys.join(", ")}`
+    );
+  }
+  const projects = {};
+  for (const [name, value] of Object.entries(rawProjects)) {
+    if (name === "__proto__") {
+      throw new ProjectsConfigError(`"__proto__" cannot be used as a key in "projects": ${configPath}`);
+    }
+    if (typeof value !== "string" || !isAbsolute(value)) {
+      console.warn(`[projects-config] invalid projects.${name}: expected an absolute path, skipping`);
+      continue;
+    }
+    if (!isDirectory(value)) {
+      console.warn(`[projects-config] projects.${name} does not exist as a directory: ${value}, skipping`);
+      continue;
+    }
+    projects[name] = value;
+  }
+  const projectGroups = {};
+  for (const [groupName, value] of Object.entries(rawProjectGroups)) {
+    if (groupName === "__proto__") {
+      throw new ProjectsConfigError(`"__proto__" cannot be used as a key in "projectGroups": ${configPath}`);
+    }
+    if (!Array.isArray(value)) {
+      console.warn(`[projects-config] invalid projectGroups.${groupName}: expected an array, skipping`);
+      continue;
+    }
+    const members = [];
+    for (const member of value) {
+      if (typeof member !== "string" || !Object.prototype.hasOwnProperty.call(projects, member)) {
+        console.warn(
+          `[projects-config] projectGroups.${groupName} references unknown project "${String(member)}", skipping`
+        );
+        continue;
+      }
+      members.push(member);
+    }
+    projectGroups[groupName] = members;
+  }
+  return { projects, projectGroups };
+}
+function resolveTargetProjects(requested, config) {
+  const resolved = /* @__PURE__ */ new Map();
+  for (const name of requested) {
+    if (name === RESERVED_ALL) {
+      for (const [projectName, projectPath] of Object.entries(config.projects)) {
+        resolved.set(projectName, { name: projectName, path: projectPath });
+      }
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(config.projects, name)) {
+      resolved.set(name, { name, path: config.projects[name] });
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(config.projectGroups, name)) {
+      for (const projectName of config.projectGroups[name]) {
+        const projectPath = config.projects[projectName];
+        if (projectPath === void 0) continue;
+        resolved.set(projectName, { name: projectName, path: projectPath });
+      }
+      continue;
+    }
+    const availableProjects = Object.keys(config.projects).join(", ") || "(none)";
+    const availableGroups = Object.keys(config.projectGroups).join(", ") || "(none)";
+    throw new ProjectsConfigError(
+      `Unknown project or group: "${name}". Available projects: ${availableProjects}. Available groups: ${availableGroups}.`
+    );
+  }
+  const resolvedProjects = Array.from(resolved.values());
+  if (resolvedProjects.length === 0) {
+    throw new ProjectsConfigError(`No projects resolved from requested targets: ${requested.join(", ")}`);
+  }
+  return resolvedProjects;
+}
+
 // src/index.ts
 var WORKERS = {
   "exec-issue": execIssueWorker,
@@ -1856,7 +2451,7 @@ var WORKERS = {
   "epic-issue": epicIssueWorker
 };
 function printUsage() {
-  console.log(`Usage: claude-task-worker <command> [--epic <issue-number>] [--label <label-name>]
+  console.log(`Usage: claude-task-worker <command> [--project <name>] [--epic <issue-number>] [--label <label-name>]
 
 Commands:
   init [--force]    Create required GitHub labels and config file (use --force to overwrite existing files)
@@ -1880,6 +2475,7 @@ Workers:
   yolo              Poll all workers including triage-created-issue, triage-pr, check-dependabot
 
 Options:
+  --project <name>  Dispatch to project(s) via herdr instead of running the worker locally. Accepts a project name, a project group name, or "all". Repeatable.
   --epic <number>   Limit issue-based workers to sub-issues of the specified epic issue. Repeatable: any matching parent (OR).
   --label <name>    Limit issue-based workers to issues that also carry the specified label. Repeatable: all must be present (AND).
 
@@ -1890,7 +2486,10 @@ Example:
   claude-task-worker all --epic 100 --epic 200
   claude-task-worker all --label priority-high
   claude-task-worker all --label priority-high --label needs-design
-  claude-task-worker yolo --epic 100 --epic 200 --label priority-high`);
+  claude-task-worker yolo --epic 100 --epic 200 --label priority-high
+  claude-task-worker all --project all
+  claude-task-worker all --project igsa
+  claude-task-worker exec-issue --project my-app --epic 100`);
 }
 var workerType = process.argv[2];
 if (workerType === "version" || workerType === "--version" || workerType === "-v") {
@@ -1906,7 +2505,10 @@ if (workerType !== "all" && workerType !== "yolo" && workerType !== "init" && wo
   printUsage();
   process.exit(1);
 }
-function collectFlagValues(flag) {
+if (hasProjectFilter()) {
+  assertProjectCompatibleCommand(workerType);
+}
+function collectFlagValues2(flag) {
   const values = [];
   for (let i = 0; i < process.argv.length; i++) {
     if (process.argv[i] !== flag) continue;
@@ -1920,7 +2522,7 @@ function collectFlagValues(flag) {
   return values;
 }
 function parseEpicFilters() {
-  const raws = collectFlagValues("--epic");
+  const raws = collectFlagValues2("--epic");
   return raws.map((raw) => {
     const num = Number(raw);
     if (!Number.isFinite(num) || !Number.isInteger(num) || num <= 0) {
@@ -1931,40 +2533,68 @@ function parseEpicFilters() {
   });
 }
 function parseLabelFilters() {
-  return collectFlagValues("--label");
+  return collectFlagValues2("--label");
 }
 process.on("unhandledRejection", (err) => {
   console.error("[worker] unhandled rejection:", err);
   process.exit(1);
 });
-process.on("SIGTERM", async () => {
-  if (isShuttingDown()) return;
-  setShuttingDown();
-  console.log(
-    "\n[worker] Stopping new tasks. Waiting for in-flight tasks to finish... (Send SIGTERM again to force kill)"
-  );
-  await waitForAllProcesses();
-  process.exit(0);
-});
-var forceKilling = false;
-process.on("SIGINT", async () => {
-  if (isShuttingDown()) {
-    if (forceKilling) return;
-    forceKilling = true;
-    console.log("\n[worker] Force killing running tasks... (cleaning up labels and worktrees)");
-    shutdown("SIGKILL");
-    const cleanupTimeout = new Promise((resolve2) => setTimeout(resolve2, 6e4).unref());
-    await Promise.race([waitForAllProcesses(), cleanupTimeout]);
-    process.exit(1);
-  }
-  setShuttingDown();
-  console.log(
-    "\n[worker] Stopping new tasks. Waiting for in-flight tasks to finish... (Press Ctrl-C again to force kill)"
-  );
-  await waitForAllProcesses();
-  process.exit(0);
-});
-if (workerType === "init") {
+if (!hasProjectFilter()) {
+  process.on("SIGTERM", async () => {
+    if (isShuttingDown()) return;
+    setShuttingDown();
+    console.log(
+      "\n[worker] Stopping new tasks. Waiting for in-flight tasks to finish... (Send SIGTERM again to force kill)"
+    );
+    await waitForAllProcesses();
+    process.exit(0);
+  });
+  let forceKilling = false;
+  process.on("SIGINT", async () => {
+    if (isShuttingDown()) {
+      if (forceKilling) return;
+      forceKilling = true;
+      console.log("\n[worker] Force killing running tasks... (cleaning up labels and worktrees)");
+      shutdown("SIGKILL");
+      const cleanupTimeout = new Promise((resolve2) => setTimeout(resolve2, 6e4).unref());
+      await Promise.race([waitForAllProcesses(), cleanupTimeout]);
+      process.exit(1);
+    }
+    setShuttingDown();
+    console.log(
+      "\n[worker] Stopping new tasks. Waiting for in-flight tasks to finish... (Press Ctrl-C again to force kill)"
+    );
+    await waitForAllProcesses();
+    process.exit(0);
+  });
+}
+if (hasProjectFilter()) {
+  (async () => {
+    let sessions = /* @__PURE__ */ new Map();
+    let monitorHandle;
+    const handleShutdown = async () => {
+      const { shutdownDispatcher: shutdownDispatcher2 } = await init_dispatcher().then(() => dispatcher_exports);
+      await shutdownDispatcher2(sessions, monitorHandle);
+    };
+    process.on("SIGTERM", handleShutdown);
+    process.on("SIGINT", handleShutdown);
+    const herdr = await Promise.resolve().then(() => (init_herdr(), herdr_exports));
+    try {
+      const config = loadProjectsConfig();
+      const projects = resolveTargetProjects(parseProjectFilters(), config);
+      const forwardedCommand = buildForwardedCommand(process.argv.slice(2));
+      const { runDispatcher: runDispatcher2, monitorSessions: monitorSessions2 } = await init_dispatcher().then(() => dispatcher_exports);
+      sessions = await runDispatcher2(projects, forwardedCommand);
+      monitorHandle = monitorSessions2(sessions, herdr);
+    } catch (err) {
+      if (err instanceof ProjectsConfigError || err instanceof herdr.HerdrUnavailableError) {
+        console.error(`[dispatcher] ${err.message}`);
+        process.exit(1);
+      }
+      throw err;
+    }
+  })();
+} else if (workerType === "init") {
   const force = process.argv.slice(3).includes("--force");
   init({ force });
 } else if (workerType === "install") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-task-worker",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "CLI tool that polls GitHub Issues/PRs and delegates work to Claude CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,7 @@
     "dev": "tsc --noEmit --watch",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "test": "node --experimental-strip-types --test src/**/*.test.ts",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "prepublishOnly": "npm run build"
@@ -39,7 +40,7 @@
   "author": "getty104",
   "license": "MIT",
   "engines": {
-    "node": ">=20"
+    "node": ">=22.6.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",