@tyhld/conductor 0.3.0

package/README.md

@@ -0,0 +1,339 @@
+# @tyhld/conductor（見守りアプリ / conductor-agent）
+
+采配くん管制の「見守りアプリ」です。
+各PCで動かしておくと、**自分がいま作業中であること（生存報告 / heartbeat）** を、
+30秒ごとに中央サーバー（devlog-tracker）へ自動で送り続けます。
+
+中央の管制画面では、どのPCがどの現場（リポジトリ）で、どのブランチを、
+作業中(working)か待機中(idle)かが一覧で見えるようになります。
+
+> 仕組みはシンプルです。あなたのPCから中央へ「生きてます」という小さな合図を
+> 定期的に送るだけ。難しい設定は要りません。
+
+---
+
+## これは何をするもの？
+
+- `conductor start` を実行すると、その場で常駐します。
+- 起動した瞬間に1回、そのあとは **30秒ごと**（変更可）に中央へ報告します。
+- 報告する内容: PC名 / 現場名(リポ名) / ブランチ名 / 状態(working/idle) / 直近の作業メモ。
+- 止めたいときは **Ctrl+C** を押すだけです。
+
+現場名（site）とブランチ名は、コマンドを実行したフォルダの git 情報から**自動で判定**します。
+git のフォルダでなければ、現在のフォルダ名を現場名として使います。
+
+---
+
+## 必要なもの
+
+- Node.js **18以上**（`node -v` で確認できます）
+
+---
+
+## 導入（他PC向け / git clone 方式）
+
+メンバーの各PCで conductor を導入・起動する手順です。**3人規模では git clone での配布で十分**なので、現段階では GitHub Packages への publish は行いません（人数が増えたら publish 配布を再検討します）。
+
+### 前提
+
+- **Node.js 18以上**（`node -v` で確認）
+- **git**
+- 対象リポジトリへのアクセス権（GitHub `tyhld` org）
+
+### 手順
+
+```bash
+# 1) clone（URL は conductor リポジトリのもの）
+git clone https://github.com/tyhld/conductor.git
+cd conductor
+
+# 2) 依存インストール
+npm install
+
+# 3) ビルド（tsc で dist/ を生成）
+npm run build
+```
+
+### 各自で設定する環境変数
+
+| 環境変数 | 値 | 備考 |
+|----------|----|------|
+| `CONDUCTOR_URL` | `https://<your-conductor-host>`（中央） | 接続先 |
+| `CONDUCTOR_SHARED_SECRET` | **Bitwarden から取得** | 共有シークレット。値はここに書きません |
+| `CONDUCTOR_MACHINE` | 任意 | PC識別名。未設定なら `os.hostname()` |
+
+> 🔑 **鍵（`CONDUCTOR_SHARED_SECRET`）は Bitwarden の共有項目から取得してください。**
+> コード・リポジトリ・この README には値を一切書きません。
+
+設定して起動する例:
+
+```bash
+export CONDUCTOR_URL=https://<your-conductor-host>
+read -s -p 'shared secret: ' CONDUCTOR_SHARED_SECRET && export CONDUCTOR_SHARED_SECRET
+node dist/cli.js start            # もしくは scripts/conductor-start.sh（後述）
+```
+
+> 補足: `npm install -g` でのグローバル導入や GitHub Packages での publish 配布は現段階では行いません。clone したリポジトリ内で `node dist/cli.js start`（または補助スクリプト）を使う運用です。
+
+---
+
+## 使い方
+
+最低限、次の2つの環境変数を渡して `conductor start` を実行します。
+
+```bash
+CONDUCTOR_URL=https://<your-conductor-host> \
+CONDUCTOR_SHARED_SECRET=（共有シークレット） \
+  conductor start
+```
+
+実行すると、こんな1行ログが定期的に流れます。
+
+```
+[conductor] 開始: machine=my-pc site=kenzokun status=working interval=30s url=https://...
+[conductor] 10:00:00 site=kenzokun status=working -> HTTP 200 OK
+[conductor] 10:00:30 site=kenzokun status=working -> HTTP 200 OK
+```
+
+止めるときは **Ctrl+C**。
+
+### よく使うオプション
+
+```bash
+# 現場名を手動で指定したいとき
+conductor start -s kenzokun
+
+# 待機中として報告したいとき
+conductor start -t idle
+
+# 直近の作業メモを添えたいとき
+conductor start -a "ログイン画面を実装中"
+```
+
+| 引数 | 意味 | 既定値 |
+|------|------|--------|
+| `-s <site>` | 現場名（リポ名） | git リポ名 → 無ければカレントフォルダ名 |
+| `-t <idle\|working>` | 状態 | `working` |
+| `-a <lastAction>` | 直近の作業メモ（自由文） | `heartbeat` |
+
+---
+
+## 環境変数一覧
+
+| 環境変数 | 必須 | 意味 | 既定値 |
+|----------|------|------|--------|
+| `CONDUCTOR_URL` | ✅ | 中央(devlog-tracker)のベースURL。例: `https://<your-conductor-host>` | （なし） |
+| `CONDUCTOR_SHARED_SECRET` | ✅ | 共有シークレット。中央API側の同名 env と一致させます | （なし） |
+| `CONDUCTOR_MACHINE` | – | PCの識別名 | `os.hostname()`（PCのホスト名） |
+| `CONDUCTOR_INTERVAL_SEC` | – | heartbeat送信間隔（秒） | `30` |
+| `CONDUCTOR_RELAY_ENABLED` | – | `true` で relay（指示の取得→アイドル時のみ tmux 送信→完了検出）を有効化 | `false` |
+| `CONDUCTOR_RELAY_INTERVAL_SEC` | – | relay のポーリング間隔（秒） | `15` |
+
+> **relay（ADR-029 段階3 / 既定 off）**：`CONDUCTOR_RELAY_ENABLED=true` のときだけ、
+> 中央から自分宛(machine+site)の指示を取得し、**送信先のtmuxセッション（名前 = 現場名 site）が
+> 完全にアイドルのときだけ** 指示を流し込みます。少しでも作業中っぽければ送らず次回に再挑戦する
+> 保守的な判定（「誤爆より送り遅れ」）です。off の間は従来どおり heartbeat のみで挙動は変わりません。
+
+---
+
+## よくある質問
+
+**Q. オフライン（offline）は送らないの？**
+A. 送りません。中央側は「最後の生存報告からの経過時間」でオフラインを判定する設計です。
+そのため Ctrl+C で止めると、しばらく後に中央画面側で自動的にオフライン表示になります。
+
+**Q. 鍵（シークレット）はどこに書くの？**
+A. **コードやリポジトリには絶対に書きません。** 実行時に環境変数で渡してください。
+
+---
+
+## 補助スクリプト: CC2のワンタッチ起動（scripts/cc2.sh）★推奨
+
+CC2（人が起動する Claude Code）の起動手順を1コマンドに畳んで、**起動ミスを根治**するためのスクリプトです。
+「箱(tmux)が未起動なのに気づかず指示だけ待機」「cd 忘れ / `unset` 忘れ / 現場名のタイプミス / 二重起動」を構造的に防ぎます。
+
+```bash
+bash scripts/cc2.sh <現場名>   # 例: bash scripts/cc2.sh kenzokun
+```
+
+`~/.bashrc` に次の alias を足すと、`cc2 kenzokun` だけで起動できます（**.bashrc の自動編集はしません。手動で追記してください**）:
+
+```bash
+alias cc2='bash ~/projects/conductor/scripts/cc2.sh'
+```
+
+やること:
+
+- 引数なし → usage と**登録済み現場一覧**（`sites.sh`）を表示して終了。
+- 未知の現場名 → **似た候補を提示（タイプミス検出）**してから一覧を表示。
+- **二重起動防止**: 同名 tmux セッションがあれば attach するだけ（並列禁止）。同じディレクトリで動く別名セッションがあれば軽く警告。
+- 新規セッションは作業ディレクトリで作成 → `unset ANTHROPIC_API_KEY` → `claude` を起動 → attach。**cd 忘れ・unset 忘れを構造的に不可能**にします。
+
+> 現場名→ディレクトリの対応表は `scripts/sites.sh` を**単一の真実**として再利用します（対応表を二重定義しない）。
+> **新しい現場は `sites.sh` を直すだけで `cc2.sh` も自動対応**します。破壊的操作（tmux kill 等）はしません。
+
+---
+
+## 補助スクリプト: CC2の起動（scripts/cc2-start.sh）
+
+人が CC2（Claude Code）を起動するときの「tmux new → cd → `unset ANTHROPIC_API_KEY` → `claude`」を1コマンドにまとめた補助です（常駐/報告役とは無関係）。`cc2.sh` の前身で、タイプミス検出・同ディレクトリ警告は付いていません（基本動作は同じ）。
+
+```bash
+bash scripts/cc2-start.sh <現場名>   # 例: bash scripts/cc2-start.sh kenzokun
+```
+
+引数なし・未知の現場名で実行すると、有効な現場名一覧を表示します。同名の tmux セッションが既にあればそこへ接続し、無ければ作成して CC2 を起動します。
+
+> 現場名→ディレクトリの対応表は `scripts/sites.sh` に集約し、`cc2-start.sh` と `conductor-start.sh` の両方が source して共有します（重複を持たない）。
+
+---
+
+## 補助スクリプト: 報告役の常駐起動（scripts/conductor-start.sh）
+
+報告役（heartbeat、必要なら relay）を1コマンドで起動する補助です。`cc2-start.sh` と同じ作法・同じ対応表を使います。
+
+```bash
+bash scripts/conductor-start.sh <現場名> [--relay]
+
+# 例
+bash scripts/conductor-start.sh kenzokun           # heartbeat のみ
+bash scripts/conductor-start.sh kenzokun --relay   # heartbeat + relay
+```
+
+- 第1引数＝現場名（`sites.sh` の対応表から作業ディレクトリを解決）。
+- `--relay` 指定時のみ relay（`CONDUCTOR_RELAY_ENABLED=true`）を有効化します。
+- 内部では現場のディレクトリへ `cd` してから `node dist/cli.js start -s <現場> -t working -a "<現場>稼働"` を実行します（ブランチ名を現場の git から判定するため）。
+- `CONDUCTOR_URL` / `CONDUCTOR_SHARED_SECRET` は**呼び出し元のシェルに設定済み前提**で、スクリプトに鍵は書きません。未設定なら案内を出して終了します。
+- 未知の現場名・引数なしのときは有効な現場名一覧を表示します。
+
+> これは **人がログイン後に1回叩く半自動** です。PC起動時の完全自動は次の「自動常駐」を使います。
+
+---
+
+## relay を手動で起動する（テスト・手動運用 / scripts/relay-start.sh）
+
+relay（指示を CC2 に流す役）を **1コマンドで手動起動**する補助です。これまで毎回打っていた `source ~/.conductor.env` → 各種 `export` → `node dist/cli.js start ...` を1コマンドにまとめ、source した鍵が子プロセス(node)に渡らない「未設定エラー」事故も `set -a` で根治しています。
+
+```bash
+bash scripts/relay-start.sh <現場名> [作業ラベル]
+
+# 例
+bash scripts/relay-start.sh relaytest
+bash scripts/relay-start.sh relaytest "スタートアップ調査"
+
+# relay 間隔を短くしてテスト（既定 15秒）
+CONDUCTOR_RELAY_INTERVAL_SEC=5 bash scripts/relay-start.sh relaytest
+```
+
+- 鍵（`CONDUCTOR_URL` / `CONDUCTOR_SHARED_SECRET`）は `~/.conductor.env` から**自動読込**します。スクリプトには鍵を書かず、画面にも値を出しません。鍵ファイルが無ければ案内して終了します。
+- `CONDUCTOR_RELAY_ENABLED=true` を付けて relay を有効化します。間隔は `CONDUCTOR_RELAY_INTERVAL_SEC`（既定 15秒）で上書き可。
+- どのディレクトリから実行しても OK（スクリプト位置からリポルートを解決）。`dist/cli.js` が無ければ `npm run build` を案内して終了します。
+- 作業ラベル（第2引数）の既定は `relay手動起動` です。
+
+---
+
+## PC起動時の自動常駐（第1段 / scripts/autostart.sh）
+
+リストに並べた現場を、それぞれ **heartbeat のみ** でバックグラウンド常駐させる、人手を介さない起動口です。WSL 上で `bash scripts/autostart.sh` を叩くと、リストの現場をまとめて常駐させます。
+
+### 1) 鍵ファイル `$HOME/.conductor.env` を用意
+
+鍵はスクリプトに書きません。各PCのホームに `$HOME/.conductor.env` を作り、そこから読み込みます。
+
+```bash
+cat > "$HOME/.conductor.env" <<'EOF'
+CONDUCTOR_URL=https://<your-conductor-host>
+CONDUCTOR_SHARED_SECRET=（Bitwarden から取得した値を貼る）
+EOF
+chmod 600 "$HOME/.conductor.env"   # 自分だけ読める権限に
+```
+
+> 🔑 `CONDUCTOR_SHARED_SECRET` の値は **Bitwarden の共有項目から取得**してください。
+> `$HOME/.conductor.env` は **git 管理外**（リポジトリには入れません）。このファイルが無い／鍵が空のときは案内を出して終了します。
+
+### 2) 自動起動する現場リスト
+
+「このPCで自動起動する現場」を1行1現場で並べます（`#` 始まりと空行は無視）。優先順位:
+
+1. `bash scripts/autostart.sh <リストファイル>` の第1引数
+2. `$HOME/.conductor.autostart.list`（各PC個別・git管理外）
+3. `scripts/autostart.list`（同梱サンプル）
+
+各PCでは `$HOME/.conductor.autostart.list` を置く（または同梱の `scripts/autostart.list` を編集する）運用です。
+
+### 3) 起動と停止
+
+```bash
+bash scripts/autostart.sh          # リストの現場を heartbeat のみで常駐起動
+bash scripts/autostart-stop.sh     # 自動常駐(node dist/cli.js start)をまとめて停止
+```
+
+- 各現場のログは `$HOME/.conductor-logs/<現場>.log` に追記されます。
+- 既に同じ現場の自動常駐が動いていれば二重起動しません。未知の現場名は warn を出してスキップします（全体は止めません）。
+- relay は有効化しません（heartbeat のみ）。relay が要るときは `conductor-start.sh --relay` を使ってください。
+
+> 停止スクリプトは `dist/cli.js start` を含む node を対象にするため、`conductor-start.sh` や手動起動の報告役も一緒に止まります。
+
+### 補足
+
+- **Windows タスクスケジューラからの呼び出しは人間が別途設定**します（このリポジトリでは設定しません）。
+- 次段では、自動起動する現場の **②管制画面からのトグル化**（ファイル編集なしで ON/OFF）を予定しています。
+
+---
+
+## PC起動時の自動常駐（第2段 / systemd ユーザーサービス）
+
+第1段（`autostart.sh`）を **systemd ユーザーサービス**に置き換えたものです。各現場を `conductor@<現場>.service` として登録し、**`Restart=always` で「落ちても自動復活」** します。これが常用、旧 `autostart.sh` は **手動予備として温存**します。
+
+### 前提
+
+- WSL で **systemd が有効**（`/etc/wsl.conf` の `[boot] systemd=true`、`[user] default=fshim`）。`systemctl --user` が使えること。
+- 鍵ファイル `$HOME/.conductor.env`（`chmod 600` / git管理外）が用意済み。中身は第1段と同じ（`CONDUCTOR_URL` / `CONDUCTOR_SHARED_SECRET`）。**鍵はリポジトリに入れません。**
+- conductor リポで `npm run build` 済み（`dist/cli.js` が存在）。
+
+### 導入
+
+```bash
+bash scripts/systemd-install.sh          # リストの現場を登録＋起動（enable --now）
+```
+
+- ユニット `systemd/conductor@.service` を `~/.config/systemd/user/` にコピーし、`daemon-reload`。
+- リストファイル（第1段と同じ優先順: 第1引数 → `$HOME/.conductor.autostart.list` → `scripts/autostart.list`）の各現場を `systemctl --user enable --now conductor@<現場>`。
+- `loginctl enable-linger $USER` を実行（ログオフ中・PC起動直後でもユーザーサービスが動くように）。通常 sudo は不要です。
+- `$HOME/.conductor.env` が無ければ警告して中断します。
+- relay は有効化しません（heartbeat のみ）。
+
+> **WorkingDirectory**: 報告役はカレントの git からブランチを判定するため、現場ディレクトリで起動します。既定は `%h/projects/<現場>`（現状は「現場名 = ディレクトリ名」で一致）。将来この2つが食い違う現場が出た場合は、install スクリプトが `sites.sh` の対応表を見て drop-in（`conductor@<現場>.service.d/override.conf`）で `WorkingDirectory` を上書きします。テンプレート本体は触りません。
+
+### 状態確認
+
+```bash
+systemctl --user status 'conductor@*'              # 全現場のサービス状態
+systemctl --user list-units 'conductor@*'          # 一覧
+journalctl --user -u 'conductor@kenzokun' -f       # 特定現場のログを追尾
+```
+
+### 停止 / 無効化
+
+```bash
+bash scripts/systemd-uninstall.sh        # 各現場を disable --now ＋ユニット削除＋daemon-reload
+```
+
+- linger は外しません（他用途の可能性があるため報告のみ）。完全に戻すときは手動で `loginctl disable-linger "$USER"`。
+
+### 補足
+
+- **落ちても `Restart=always`（`RestartSec=5`）で自動復活**します。第1段の `nohup &` と違い、クラッシュ・OOM 後も systemd が起こし直します。
+- 旧 `scripts/autostart.sh` は **手動予備として温存**（常用は systemd）。
+- **Windows タスクスケジューラは「WSL を起こす」役割に変更**します（常駐の起動は systemd が担当）。例: ログオン時に `wsl.exe -d Ubuntu -u fshim true` 等で WSL を立ち上げるだけ。この変更は**人間が別途設定**します。
+- 次段では、自動起動する現場の **②管制画面からのトグル化**（ファイル編集なしで ON/OFF）を予定しています。
+
+---
+
+## 開発
+
+```bash
+npm install
+npm run build      # tsc で dist/ を生成
+npm start          # = node dist/cli.js start
+```

package/dist/cli.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/**
+ * @tyhld/conductor — 采配くん管制の「見守りアプリ（conductor-agent）」。
+ *
+ * 各PC（現場）で常駐し、中央 devlog-tracker の報告API
+ *   POST {CONDUCTOR_URL}/api/conductor/report
+ * へ、起動直後に1回 + 以後 CONDUCTOR_INTERVAL_SEC 秒ごとに生存報告(heartbeat)を送る。
+ *
+ * 認可は共有シークレットの Bearer のみ（API 側 env CONDUCTOR_SHARED_SECRET と一致させる）。
+ * 鍵はコードに書かず、必ず環境変数で渡す。
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+import { createRelayState, relayTick, tmuxHasSession } from './relay.js';
+/** git コマンドを安全に実行し、失敗したら null を返す（git でない/未インストール等）。 */
+function git(args) {
+    try {
+        const out = execFileSync('git', args, {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+        });
+        const trimmed = out.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 現在のブランチ名（取れなければ null）。 */
+function detectBranch() {
+    return git(['rev-parse', '--abbrev-ref', 'HEAD']);
+}
+/** 現場名(site): git リポのトップ階層フォルダ名。git でなければカレントフォルダ名。 */
+function detectSite() {
+    const top = git(['rev-parse', '--show-toplevel']);
+    const dir = top ?? process.cwd();
+    // 末尾のセパレータを除いた最後の要素を取る（Windows の \ にも一応対応）。
+    const parts = dir.replace(/[\\/]+$/, '').split(/[\\/]/);
+    return parts[parts.length - 1] || dir;
+}
+/**
+ * 引数を簡易パース。`conductor start [-s site] [-t status] [-a lastAction]`。
+ * 余計な依存を足さないため自前で処理する。
+ */
+function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    const result = {
+        command,
+    };
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        const next = rest[i + 1];
+        switch (arg) {
+            case '-s':
+            case '--site':
+                result.site = next;
+                i++;
+                break;
+            case '-t':
+            case '--status':
+                result.status = next;
+                i++;
+                break;
+            case '-a':
+            case '--action':
+                result.lastAction = next;
+                i++;
+                break;
+            default:
+                // 未知の引数は無視（将来の拡張余地）。
+                break;
+        }
+    }
+    return result;
+}
+/** わかりやすいエラーを出して終了。 */
+function fail(message) {
+    console.error(`[conductor] エラー: ${message}`);
+    process.exit(1);
+}
+/** 環境変数＋引数から設定を組み立てる。必須が無ければここで終了する。 */
+function loadConfig(args) {
+    const url = (process.env.CONDUCTOR_URL ?? '').trim();
+    const secret = (process.env.CONDUCTOR_SHARED_SECRET ?? '').trim();
+    if (!url) {
+        fail('環境変数 CONDUCTOR_URL が未設定です（例: CONDUCTOR_URL=https://<your-conductor-host>）');
+    }
+    if (!secret) {
+        fail('環境変数 CONDUCTOR_SHARED_SECRET が未設定です（中央APIと同じ共有シークレットを渡してください）');
+    }
+    const machine = (process.env.CONDUCTOR_MACHINE ?? '').trim() || os.hostname();
+    const status = (args.status ?? 'working').trim();
+    if (status !== 'idle' && status !== 'working') {
+        fail(`status は idle か working を指定してください（指定値: "${status}"）`);
+    }
+    const site = (args.site ?? '').trim() || detectSite();
+    const lastAction = (args.lastAction ?? '').trim() || 'heartbeat';
+    let intervalSec = 30;
+    const rawInterval = (process.env.CONDUCTOR_INTERVAL_SEC ?? '').trim();
+    if (rawInterval) {
+        const parsed = Number(rawInterval);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            fail(`CONDUCTOR_INTERVAL_SEC は正の数で指定してください（指定値: "${rawInterval}"）`);
+        }
+        intervalSec = parsed;
+    }
+    // relay 設定（既定 off。off の間は既存の heartbeat 挙動を一切変えない）。
+    const relayEnabled = /^(1|true|yes|on)$/i.test((process.env.CONDUCTOR_RELAY_ENABLED ?? '').trim());
+    let relayIntervalSec = 15;
+    const rawRelayInterval = (process.env.CONDUCTOR_RELAY_INTERVAL_SEC ?? '').trim();
+    if (rawRelayInterval) {
+        const parsed = Number(rawRelayInterval);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            fail(`CONDUCTOR_RELAY_INTERVAL_SEC は正の数で指定してください（指定値: "${rawRelayInterval}"）`);
+        }
+        relayIntervalSec = parsed;
+    }
+    return {
+        url: url.replace(/\/+$/, ''),
+        secret,
+        machine,
+        site,
+        status,
+        lastAction,
+        intervalSec,
+        relayEnabled,
+        relayIntervalSec,
+    };
+}
+/** 1回分の報告を送る。送信結果（HTTPステータス）をログ表示する。 */
+async function sendReport(cfg) {
+    const body = {
+        machine: cfg.machine,
+        site: cfg.site,
+        branch: detectBranch(),
+        status: cfg.status,
+        lastAction: cfg.lastAction,
+        artisanReady: tmuxHasSession(cfg.site),
+    };
+    const time = new Date().toLocaleTimeString();
+    try {
+        const res = await fetch(`${cfg.url}/api/conductor/report`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${cfg.secret}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        const ok = res.ok ? 'OK' : 'NG';
+        console.log(`[conductor] ${time} site=${cfg.site} status=${cfg.status} -> HTTP ${res.status} ${ok}`);
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            if (text)
+                console.log(`[conductor]   応答: ${text.slice(0, 200)}`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.log(`[conductor] ${time} site=${cfg.site} status=${cfg.status} -> 送信失敗: ${msg}`);
+    }
+}
+/** `conductor start`: 起動直後に1回 + 以後 intervalSec ごとに報告し続ける。 */
+async function start(args) {
+    const cfg = loadConfig(args);
+    console.log(`[conductor] 開始: machine=${cfg.machine} site=${cfg.site} status=${cfg.status} ` +
+        `interval=${cfg.intervalSec}s url=${cfg.url}`);
+    console.log('[conductor] 停止するには Ctrl+C を押してください。');
+    // 起動直後に1回。
+    await sendReport(cfg);
+    const timer = setInterval(() => {
+        void sendReport(cfg);
+    }, cfg.intervalSec * 1000);
+    // ADR-029 relay。CONDUCTOR_RELAY_ENABLED=true のときだけ別インターバルで回す。
+    // heartbeat とは独立。off の間は何も起きない（既存挙動を壊さない）。
+    let relayTimer = null;
+    if (cfg.relayEnabled) {
+        console.log(`[relay] 有効: site=${cfg.site} interval=${cfg.relayIntervalSec}s ` +
+            `（tmuxセッション "${cfg.site}" がアイドルのときだけ送信します）`);
+        const relayState = createRelayState();
+        relayTimer = setInterval(() => {
+            void relayTick(cfg, relayState);
+        }, cfg.relayIntervalSec * 1000);
+    }
+    // Ctrl+C で綺麗に停止。
+    // ※ 中央APIは status を idle|working のみ受理し offline は受け付けない
+    //   （オフライン判定は heartbeat の鮮度から画面側で行う設計）。
+    //   そのため終了時は余計な送信をせず、タイマーを止めて静かに終わる。
+    const stop = () => {
+        clearInterval(timer);
+        if (relayTimer)
+            clearInterval(relayTimer);
+        console.log('\n[conductor] 停止しました。');
+        process.exit(0);
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+}
+/** package.json の version を返す（読めなければ 'unknown'）。dist/cli.js からは ../package.json。 */
+function readVersion() {
+    try {
+        const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function printVersion() {
+    console.log(readVersion());
+}
+function printUsage() {
+    console.log([
+        '@tyhld/conductor — 生存報告(heartbeat)常駐CLI',
+        '',
+        '使い方:',
+        '  conductor start [-s <site>] [-t <idle|working>] [-a <lastAction>]',
+        '',
+        '必須の環境変数:',
+        '  CONDUCTOR_URL            中央(devlog-tracker)のベースURL',
+        '  CONDUCTOR_SHARED_SECRET  共有シークレット（中央APIと一致させる）',
+        '',
+        '任意の環境変数:',
+        '  CONDUCTOR_MACHINE        PC識別名（既定: os.hostname()）',
+        '  CONDUCTOR_INTERVAL_SEC   heartbeat送信間隔・秒（既定: 30）',
+        '',
+        'relay（ADR-029 段階3 / 既定off。tmuxセッション名=site の現場が対象）:',
+        '  CONDUCTOR_RELAY_ENABLED       true で relay 有効（既定: false）',
+        '  CONDUCTOR_RELAY_INTERVAL_SEC  relayポーリング間隔・秒（既定: 15）',
+        '',
+        '例:',
+        '  CONDUCTOR_URL=https://<your-conductor-host> \\',
+        '    CONDUCTOR_SHARED_SECRET=*** conductor start',
+    ].join('\n'));
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    switch (args.command) {
+        case 'start':
+            await start(args);
+            break;
+        case 'version':
+        case '-v':
+        case '--version':
+            printVersion();
+            break;
+        case undefined:
+        case 'help':
+        case '-h':
+        case '--help':
+            printUsage();
+            break;
+        default:
+            console.error(`[conductor] 不明なコマンド: ${args.command}`);
+            printUsage();
+            process.exit(2);
+    }
+}
+void main();