@tyhld/conductor 0.3.0 → 0.7.0

package/dist/websocket-transport.js

@@ -0,0 +1,66 @@
+/**
+ * @tyhld/conductor — 耳が使う WebSocket 実装の選び方（ADR-066 / 実機 Node 20 での不具合の根治）。
+ *
+ * 【何が起きていたか】
+ *   supabase-js は WebSocket を「実行環境の標準品(globalThis.WebSocket)」から探す。これが標準で
+ *   入ったのは Node 22 からで、実機の Node 20 では見つからず
+ *     「Node.js detected but native WebSocket not found.」
+ *   で購読の開始に失敗し続けた（バックオフ再接続とポーリング肩代わりは効いていたので実害は無いが、
+ *   耳が一度も張れない＝加速がまるごと効かない）。
+ *
+ * 【なぜ「Nodeを22へ上げる」で直さないか】
+ *   采配くんはお客さまのPCで動く商品で、そのPCの Node の版はこちらで決められない。
+ *   「Nodeを上げてください」を導入条件にすると、上げられない機では永久に耳が生えない。
+ *   だから WebSocket の実装そのものをこのリポに同梱し、どの Node(18/20/22) でも耳が張れるようにする。
+ *   ＝環境に合わせて商品が動く形にする（商品に合わせて環境を直させない）。
+ *
+ * 【選び方】
+ *   ① 実行環境に標準の WebSocket があればそれを使う（Node 22+ / ブラウザ）。
+ *   ② 無ければ同梱の ws パッケージを使い、supabase-js の transport オプションへ渡す。
+ *   ③ どちらも用意できなければ耳は張らない——ただし【起動不能にはしない】。ログを残して諦め、
+ *      各 relay の15秒ポーリングでこれまでどおり動かす（便2b以来の作法）。
+ */
+/**
+ * 実行環境の標準 WebSocket を返す純粋関数（無ければ null）。
+ *   scope を引数にしてあるのは、標準品が「ある機／ない機」の両方をテストで作れるようにするため。
+ */
+export function pickNativeWebSocket(scope = globalThis) {
+    const ws = scope.WebSocket;
+    return typeof ws === 'function' ? ws : null;
+}
+/**
+ * 読み込んだ ws パッケージの形から、コンストラクタを取り出す純粋関数。
+ *   ws は既定書き出し(default)でもあり名前付き(WebSocket)でもあるので、どちらの形でも拾う。
+ *   取り出せなければ null（＝同梱品が壊れている/形が変わった。耳は張らずポーリングに任せる）。
+ */
+export function pickBundledWebSocket(mod) {
+    if (mod === null || typeof mod !== 'object')
+        return null;
+    const m = mod;
+    const candidate = typeof m.default === 'function' ? m.default : m.WebSocket;
+    return typeof candidate === 'function' ? candidate : null;
+}
+/**
+ * 耳が使う WebSocket 実装を決める。標準品 → 同梱品 の順で探し、どちらも無ければ null。
+ *   同梱品は動的 import で読む。npm install を忘れた機でも耳のプロセスごと落とさないため
+ *   （読めなければ「耳なし＝ポーリングのみ」で静かに動き続けるのが正しい）。
+ */
+export async function resolveWebSocketTransport(scope = globalThis) {
+    const native = pickNativeWebSocket(scope);
+    if (native !== null)
+        return { kind: 'native', ctor: native };
+    try {
+        const mod = await import('ws');
+        const bundled = pickBundledWebSocket(mod);
+        return bundled === null ? null : { kind: 'bundled', ctor: bundled };
+    }
+    catch {
+        return null; // 同梱品が入っていない（npm install 未実施 等）。
+    }
+}
+/** ログ用の言い回し（何を使って繋いでいるかが1行で分かるように）。 */
+export function describeTransport(transport) {
+    return transport.kind === 'native'
+        ? 'この機の標準WebSocketを使います'
+        : '同梱のWebSocket部品(ws)を使います（この機のNodeには標準のWebSocketがないため）';
+}

package/launchd/ear-install.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+#
+# ear-install.sh（launchd 版）— Mac に「耳」(conductor ear) を1本だけ設置する。★ADR-019
+#
+# ★これは systemd/ear-install.sh の「Mac 版の相方」です。役割はまったく同じで、
+#   指示が積まれた合図を受け取り、その現場の relay へ「今すぐ1周して」と伝えます（PCに1本）。
+#
+# 使い方:
+#   bash launchd/ear-install.sh
+#
+# ★best-effort: 入らなくてもセットアップは止めない。耳は加速装置であって依存先ではなく、
+#   各現場の relay は15秒ごとの確認でこれまでどおり完全に動きます（systemd 版と同じ方針）。
+#
+set -euo pipefail
+
+fail() { echo "[launchd-ear] エラー: $1" >&2; exit 1; }
+warn() { echo "[launchd-ear] warn: $1" >&2; }
+
+LABEL="com.tyhld.conductor.ear"
+
+[[ "$(uname -s)" == "Darwin" ]] || fail "これは Mac 用です。Linux/WSL では systemd/ear-install.sh を使います。"
+command -v launchctl >/dev/null 2>&1 || fail "launchctl が見つかりません。"
+
+# 鍵を読んでから起動する入れ物は、現場ごとの install.sh が作る同じものを使い回す。
+# ★耳だけを単体で入れたときのために、無ければここでも作る（作り方は1か所に寄せたいが、
+#   耳は「PCに1本」で現場に依存しないため、同じ内容を同じ場所に置く＝結果は同一）。
+RUNNER="$HOME/.tyhld/bin/conductor-run.sh"
+if [[ ! -x "$RUNNER" ]]; then
+  resolve_path() {
+    python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$1" 2>/dev/null || printf '%s' "$1"
+  }
+  command -v node >/dev/null 2>&1 || fail "node が見つかりません。"
+  command -v conductor >/dev/null 2>&1 || fail "conductor が見つかりません。"
+  NODE_BIN="$(resolve_path "$(command -v node)")"
+  CONDUCTOR_JS="$(resolve_path "$(command -v conductor)")"
+  mkdir -p "$(dirname "$RUNNER")"
+  cat > "$RUNNER" <<RUNEOF
+#!/bin/bash
+# 采配くんの常駐を起動する入れ物（launchd 用・ear-install.sh が生成）。
+set -eu
+if [ -f "\$HOME/.conductor.env" ]; then
+  set -a
+  . "\$HOME/.conductor.env"
+  set +a
+fi
+exec "$NODE_BIN" "$CONDUCTOR_JS" "\$@"
+RUNEOF
+  chmod 700 "$RUNNER"
+  echo "[launchd-ear] 起動の入れ物を配置: $RUNNER"
+fi
+
+AGENT_DIR="$HOME/Library/LaunchAgents"
+PLIST="$AGENT_DIR/${LABEL}.plist"
+LOG_DIR="$HOME/Library/Logs/tyhld"
+mkdir -p "$AGENT_DIR" "$LOG_DIR"
+
+cat > "$PLIST" <<PLISTEOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${RUNNER}</string>
+    <string>ear</string>
+  </array>
+  <key>WorkingDirectory</key><string>${HOME}</string>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>StandardOutPath</key><string>${LOG_DIR}/conductor-ear.log</string>
+  <key>StandardErrorPath</key><string>${LOG_DIR}/conductor-ear.log</string>
+</dict>
+</plist>
+PLISTEOF
+echo "[launchd-ear] 配置: $PLIST"
+
+UID_NUM="$(id -u)"
+launchctl bootout "gui/${UID_NUM}/${LABEL}" >/dev/null 2>&1 || true
+if launchctl bootstrap "gui/${UID_NUM}" "$PLIST" >/dev/null 2>&1; then
+  echo "[launchd-ear] 起動しました: $LABEL"
+else
+  launchctl unload "$PLIST" >/dev/null 2>&1 || true
+  launchctl load -w "$PLIST" >/dev/null 2>&1 \
+    && echo "[launchd-ear] 起動しました（load 方式）: $LABEL" \
+    || warn "起動に失敗しました（耳が無くても指示は15秒以内に届きます）"
+fi
+
+LEDGER_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/conductor"
+LEDGER_FILE="$LEDGER_DIR/installed-launchd.txt"
+mkdir -p "$LEDGER_DIR"
+touch "$LEDGER_FILE"
+grep -qxF "$LABEL" "$LEDGER_FILE" || echo "$LABEL" >> "$LEDGER_FILE"
+
+echo "[launchd-ear] 完了（このPCに1本）"

package/package.json

@@ -1,14 +1,27 @@
 {
   "name": "@tyhld/conductor",
-  "version": "0.3.0",
+  "version": "0.7.0",
   "description": "采配くん管制の見守りアプリ（conductor-agent）。各PCで常駐し、中央(devlog-tracker)へ定期的に生存報告(heartbeat)を送る常駐CLI。",
   "type": "module",
   "bin": {
     "conductor": "dist/cli.js"
   },
+  "_files_note": [
+    "★ここはお客さまへ届く中身そのもの（ADR-018）。1ファイルずつ挙げると必ず取りこぼす。",
+    "  実際 2026-09-02 まで scripts/hooks/cc2_guard.py だけを挙げていたため、setup.sh が要求する",
+    "  番人6本のうち5本が同梱されず、npm で配ると設置が⑤で必ず止まる状態だった。",
+    "★だからフォルダごと挙げる。新しい番人を足しても自動で同梱される＝取りこぼしが起こせない。",
+    "★同梱物は test/package-contents.test.ts が npm pack の実物を見て検査する",
+    "  （setup.sh が要る物が全部入っているか／秘密が混ざっていないか）。"
+  ],
   "files": [
     "dist",
     "sales-template",
+    "scripts/hooks",
+    "!scripts/hooks/__pycache__",
+    "skills",
+    "launchd",
+    "systemd",
     "README.md"
   ],
   "engines": {
@@ -20,7 +33,18 @@
     "test": "tsc && node --test --experimental-strip-types test/*.test.ts",
     "prepublishOnly": "npm run build"
   },
+  "_publishConfig_note": [
+    "★配布先は公開 npm（registry.npmjs.org）1本（えふさん決定 2026-09-04）。",
+    "  実測 2026-09-04: 公開 npm には 0.3.0 しか無く、0.5.0 は GitHub Packages（非公開）に出ていた。",
+    "  原因は publish 時に手元の ~/.npmrc の @tyhld スコープ設定（GitHub Packages 向き）が効くこと。",
+    "  お客さまは公開 npm の 0.3.0 を掴む。0.3.0 の dist は古い鍵名 CONDUCTOR_SHARED_SECRET を読むので、",
+    "  いまの接続情報（CONDUCTOR_TOKEN）では『未設定です』で落ちる（migakia の設置で再現）。",
+    "★registry を書いておくと、publish のときだけ効き、.npmrc のスコープ設定より優先される。",
+    "  ＝手元の設定が何であっても公開 npm へ出る。取得側（他リポの @tyhld/* 部品）は一切変えない。",
+    "★このキーは1つだけ。2つ書くと後ろが勝ち、前に書いたほうは黙って無視される（実際に踏んだ）。"
+  ],
   "publishConfig": {
+    "registry": "https://registry.npmjs.org",
     "access": "public"
   },
   "repository": {
@@ -30,6 +54,11 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^25.9.1",
+    "@types/ws": "^8.18.1",
     "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.112.4",
+    "ws": "^8.21.3"
   }
 }

package/sales-template/README.md

@@ -2,23 +2,47 @@
 
 采配くんを顧客PCにインストールするためのテンプレート一式です。
 
-## クイックスタート（1コマンドインストール）
+## クイックスタート（★お客さまが打つのはこの2行だけ）
 
 ```bash
-# @tyhld/conductor パッケージに同梱された setup.sh を実行
-bash setup.sh my-app /path/to/my-app
+npm i -g @tyhld/conductor          # 1) 采配くんを入れる
+conductor setup my-app             # 2) 設置する（現場名を指定）
 ```
 
+`conductor setup` は、配布物に同梱されたインストーラ（`sales-template/setup.sh`）を呼ぶ入口です。
+**ファイルの場所を知らなくても設置できます**（ADR-018）。
+
+- 現場のフォルダを別の場所に置いている場合: `conductor setup my-app /path/to/my-app`
+- 設置のあとに聞かれるのは **管制のアドレス**と**合言葉**の2つだけ（どちらも弊社からお渡しします）。
+  ★合言葉は入力しても画面には表示されません。
+
+<details><summary>ファイルを直接指定して実行する場合（上級者向け）</summary>
+
+```bash
+bash "$(npm root -g)/@tyhld/conductor/sales-template/setup.sh" my-app /path/to/my-app
+```
+</details>
+
+### 対応している OS
+
+| OS | 状態 |
+|---|---|
+| **Windows**（WSL2 + Ubuntu） | 対応（常駐は systemd） |
+| **Mac**（macOS） | ★**対応したが実機未検証**（常駐は launchd・ADR-019）。ログイン中だけ動きます |
+
 ### 必要なもの
 
 | 項目 | 説明 |
 |------|------|
-| Node.js 18+ | fnm / nvm / volta / apt いずれか |
-| tmux | `sudo apt install tmux` |
-| git | `sudo apt install git` |
-| Python 3.8+ | OS 標準で入っていることが多い |
-| systemd | WSL の場合: `/etc/wsl.conf` に `[boot] systemd=true` |
-| sudo | node symlink 作成（③）と linger 設定（⑥）で必要 |
+| Node.js 18+ | nvm / fnm / volta、または `sudo apt install` / `brew install` |
+| tmux | Windows: `sudo apt install tmux` ／ Mac: `brew install tmux` |
+| git | Windows: `sudo apt install git` ／ Mac: Xcode コマンドラインツールに同梱 |
+| Python 3.8+ | Windows: OS 標準 ／ Mac: Xcode CLT または `brew install python3` |
+| 常駐の仕組み | Windows(WSL): `/etc/wsl.conf` に `[boot] systemd=true` ／ Mac: launchd（標準で入っています） |
+| sudo | Windows のみ（node のリンク作成③と linger 設定⑥）。★**Mac では使いません** |
+| Claude Code | `npm i -g @anthropic-ai/claude-code` ＋ `claude` でログイン（★先に済ませてください） |
+
+> 開発・テストには Node 22 以上が要ります（`npm test` が `--experimental-strip-types` を使うため）。顧客が実行するのはコンパイル済みの JS なので 18 で足ります。
 
 ### setup.sh がやること
 
@@ -29,11 +53,15 @@ bash setup.sh <プロジェクト名> [プロジェクトディレクトリ]
  ② conductor 本体インストール (npm i -g @tyhld/conductor)
  ③ node symlink (/usr/local/bin/node → 実体)      ← sudo
  ④ .conductor.env 作成 (対話入力)                   ← URL/SECRET入力
- ⑤ .claude/ 配置 (cc2_guard.py + settings.json)
- ⑥ systemd enable (conductor@<名前>)               ← sudo (linger)
+ ⑤ 番人一式の配置 (3フックを ~/.tyhld/hooks/ へ + フックは ~/.claude/settings.json に1本)
+ ⑥ systemd enable (現場ごとの conductor@<名前> ＋ このPCに1本の耳 conductor-ear) ← sudo (linger)
  ⑦ 職人起動の案内表示
 ```
 
+> **耳（conductor-ear）**：指示が積まれた合図を受け取り、その現場の常駐へ「今すぐ確認して」と
+> 伝える役です（PCに1本）。指示が届くまでの最大15秒の待ちが消えます。
+> 入らない機でもセットアップは止まらず、常駐は15秒ごとの確認で従来どおり動きます。
+
 顧客の手数: **1コマンド + 対話2問 + sudo + Claude Code 起動 = 実質3アクション**
 
 ### インストール（認証不要）
@@ -57,8 +85,104 @@ npm i -g @tyhld/conductor
 
 | ファイル | 役割 | 設置先 |
 |----------|------|--------|
-| `cc2_guard.py` | Bash コマンド実行前の自動検査（Hook） | プロジェクトの `.claude/hooks/` に配置し、hooks 設定で PreToolUse に登録 |
-| `settings.json` | Claude Code の権限ルール（deny/allow/ask） | プロジェクトの `.claude/settings.json` として配置 |
+| 番人一式（`cc2_guard.py` ほか） | コマンド実行・ファイル書き込み・外部接続の前後で自動検査する安全装置。**段2（2026-07-23）から3フック立て**：`cc2_guard.py`（実行前チェック）／`permission_request_hook.py`（お客さまへの確認カード）／`stop_hook.py`（完了通知）と、その依存（`policy.py`／`summary_ja.py`／`hook_datalink.py`）。**実体は `scripts/hooks/`（正本1本）** | **1台に1箇所** `~/.tyhld/hooks/` に一式を設置。番人フックは**顧客PCの `~/.claude/settings.json` に1本だけ**登録し、この1台の全現場で共有します（各現場の `.claude/settings.json` には番人フックを書きません＝二重番人を作らない） |
+| `settings.json` | 各現場の権限ルール（`deny` と現場固有の `sandbox`）。**許可/確認の判定は番人が持つため `allow`・`ask` は空**（既定 allow、危険と関門だけ番人が止める） | プロジェクトの `.claude/settings.json` として配置 |
+
+> **番人(`cc2_guard.py`)はこのフォルダには置いていません。**
+> 以前はここに複製を置いていましたが、正本が更新されても複製が古いまま取り残され、
+> 守りの内容がずれてしまいました。現在は**正本1本だけ**を配布しています
+> （`setup.sh` が自動で配置するので、お客さまの作業は変わりません）。
+
+### 🌐 弊社のサービスへの接続は聞かれません
+
+職人が弊社のサービス（管制画面・保管庫・認証など）へつなぐとき、これまでは**そのたびに
+「外部へ接続してよいか」と確認**が出ていました。弊社の設備は既定で許可済みにしたので、
+**もう聞かれません**。
+
+- 許可したのは**弊社の設備だけ**です（`ty-hld.com` と弊社の認証サービス）。
+- **お客さまがお使いの外部サービス**（データベースや公開先など）は**含めていません**。
+  そちらは今までどおり、必要なときに確認が出ます。
+- すでにお使いの環境には、下の更新コマンドで届きます。
+
+### 📮 「終わりました」の報告や、読むだけの調べものは聞かれません
+
+職人が管制へ**完了を伝える**とき、**データベースの構造を読むだけ**のときなどは、人の判断が要らない安全な動作なので**確認を出さずに自動で通します**（これまでは確認が担当のパソコン側に出て、職人が止まってしまうことがありました）。
+
+- **一件ずつ許可するのではなく「職人の安全な報告・読み取り」というまとまり（カテゴリ）で許可**しています。同じ種類の道具が増えても、同じまとまりで拾えるので、そのつど設定を足す必要がありません。
+- 自動で通すのは**報告（完了通知・返信・開発ログ）**と**読み取り専用の調べもの**だけです。**書き込み・作成・変更**（データベースへの書込や設定の反映など）は**含めていません**——今までどおり止まります。
+- 鍵や秘密が写り得るものも**含めていません**。
+- すでにお使いの環境には、下の更新コマンドで届きます。
+
+### 🔄 すでにお使いの環境を最新にするには
+
+安全装置を新しくしたときは、**次の1コマンド**でこの1台のすべての現場が最新になります。
+
+```bash
+# まず「何が変わるか」を確認（書き込みません）
+bash scripts/update-guard.sh
+
+# 内容に納得したら適用
+APPLY=1 bash scripts/update-guard.sh
+```
+
+- **お客さまが加えた設定は消えません。** 変更するのは「安全装置の呼び出し先」と「禁止ルールの追加」だけで、
+  許可した作業や独自の設定はそのまま残ります。
+- **書き換える前に自動でバックアップ**を取ります（`settings.json.bak.日付`）。
+- **何度実行しても同じ結果**です。すでに最新なら「最新です」と表示して何もしません。
+- 適用後は職人（Claude Code）を再起動してください。
+- **★このコマンドを1回流すと、以後は安全装置が自動で最新になります。**
+  1時間ごとに「安全装置の中身と呼び出し先」だけを揃える見張りが入ります（許可のルールや
+  お掃除には触れません）。直したのに古いまま動き続ける、を防ぐためです（ADR-012）。
+  安全装置を作りかけの状態では配りません（作業中の壊れたものが全現場へ広がらないように）。
+
+### 🔒 秘密のファイルと安全装置は自動で守られます
+
+お客さまの環境では、次のファイルへの**書き込みが自動でお断り**されます。職人（AI）が
+うっかり、あるいは指示を取り違えて書き換えてしまう事故を防ぐためです。
+
+| 守るもの | 例 | なぜ |
+|---|---|---|
+| パスワードや鍵の設定ファイル | `.env` / `.env.local` | 接続情報が壊れる・漏れるのを防ぐ |
+| **安全装置そのもの** | `.claude/settings.json` / `.claude/hooks/` / `~/.tyhld/` | ここを書き換えられると**守り自体を外せてしまう**ため |
+| 鍵ファイル | `.ssh/` の中身 / `*.pem` / `*.key` | なりすましや不正アクセスを防ぐ |
+
+**この動作は 2026-07-20 の更新から有効です。**それ以前に設置した環境では、`.env` などへの
+書き込みが確認なしで通っていました。もし「これまで動いていた作業が止まった」場合は、
+上記のいずれかに書き込もうとしている可能性があります。**必要な作業であれば、人がご自身の手で
+編集してください**（安全装置は人の操作までは止めません）。
+
+### 🧹 貼り付けの一時ファイルは毎日自動で古い分を消します
+
+画面に貼り付けた文章の一時ファイル（`~/.claude/paste-cache`）は、毎日自動で古い分をお掃除します（既定では1日より前の分。当日分は残ります）。
+
+### 🖥️ 画面の見た目チェックを使うPCでは、最初に1回だけ
+
+職人（AI）が**できあがった画面を実際に開いて確かめる**作業（ブラウザ検品）を行うPCでは、
+その道具を**最初に1回だけ**入れてください。入れていないと、職人は確かめようとするたびに
+**「インターネットからブラウザを取り寄せてよいか」の確認**を出して手を止めます。
+この確認は管制の画面には出せず、**そのPCの黒い画面（ターミナル）でしか押せません**。
+
+```bash
+# ★どちらも conductor リポジトリの中で実行します（update-guard.sh と同じ場所）。
+
+# A) 道具を入れる（このPCに1回だけ。約150MBのダウンロードがあります）
+bash scripts/pw-browser-install.sh              # まず「何をするか」を表示（何も入れません）
+APPLY=1 bash scripts/pw-browser-install.sh      # 内容に納得したら実行
+
+# B) 保険：取り寄せ先を「聞かずに通してよい先」として各現場へ登録する
+bash scripts/update-allowed-domains.sh          # まず「何が変わるか」を確認（書き込みません）
+APPLY=1 bash scripts/update-allowed-domains.sh  # 内容に納得したら適用
+```
+
+- **道具は1台に1箇所だけ**置きます（`~/.tyhld/pw-venv` と `~/.tyhld/pw-browsers`）。
+  現場（プロジェクト）が増えても道具は増えません。
+- **入れた直後に、本当に動くところまで確認**して表示します（実物があるか／職人の作業場所から
+  見えるか／実際に起動するか）。動かなければその場で止めてお知らせします。
+- **職人は自分で入れません。** 道具が無ければ職人はそこで止まり、「人の手番です」と報告します。
+- **B は他の設定を変えません。** 「聞かずに通してよい取り寄せ先」を足すだけで、禁止ルールや
+  安全装置には一切触れません。`scripts/update-guard.sh`（全部入り）を流す場合は同じ内容が
+  一緒に届くので、B は不要です。
+- **何度実行しても同じ結果**です（すでに入っていれば何もしません）。
 
 ### 動作の仕組み（3層防御）
 
@@ -105,13 +229,19 @@ cp settings.json .claude/settings.json
 
 ```bash
 # hooks ディレクトリを作成
-mkdir -p .claude/hooks
-
-# cc2_guard.py をコピー
-cp cc2_guard.py .claude/hooks/cc2_guard.py
-chmod +x .claude/hooks/cc2_guard.py
+# ★番人は「1台に1箇所」だけ置きます（現場ごとのコピーは作りません）
+mkdir -p ~/.tyhld/hooks
+
+# 番人(正本)と、その設定ファイルをコピー
+#   ★safe_verbs.json は番人と「同じフォルダ」に置く必要があります（番人が自分の隣を読むため）。
+cp ../scripts/hooks/cc2_guard.py    ~/.tyhld/hooks/cc2_guard.py
+cp ../scripts/hooks/safe_verbs.json ~/.tyhld/hooks/safe_verbs.json 2>/dev/null || true
+chmod +x ~/.tyhld/hooks/cc2_guard.py
 ```
 
+> 通常は `setup.sh` が上記を自動で行います。手作業でのコピーは、
+> 既存環境を手直しする場合のみお使いください。
+
 Claude Code の設定（`.claude/settings.json` または `~/.claude/settings.json`）に以下を追加:
 
 ```json
@@ -123,7 +253,7 @@ Claude Code の設定（`.claude/settings.json` または `~/.claude/settings.js
         "hooks": [
           {
             "type": "command",
-            "command": "python3 .claude/hooks/cc2_guard.py"
+            "command": "python3 /home/<ユーザー名>/.tyhld/hooks/cc2_guard.py"
           }
         ]
       }
@@ -183,15 +313,45 @@ Claude Code の設定（`.claude/settings.json` または `~/.claude/settings.js
 ### cc2_guard.py の安全動詞を追加する
 
 プロジェクト固有のCLIツール（例: `turbo`, `nx`）を自動許可したい場合、
-`cc2_guard.py` の `SAFE_VERBS` セットに追加:
+**ソースは編集せず**、同梱の `safe_verbs.json`（雛形）を `cc2_guard.py` と同じディレクトリに置いて `add` に足す:
 
-```python
-SAFE_VERBS = {
-    # ... 既存の動詞 ...
-    'turbo', 'nx',  # 追加
-}
+```json
+{ "add": ["turbo", "nx"] }
 ```
 
+一時的なら環境変数でも可: `CC2_SAFE_VERBS="turbo nx"`。設定が無ければ既定値で動く（fail-safe）。
+
+> ⚠️ **allow を広げるのは信頼の委譲です。** `rm` / `sudo` / `bash` / `eval` / `psql` 等の任意実行・権限昇格・破壊系は
+> 封じてあり（`NEVER_CONFIGURABLE`）、書いても白になりません。`settings.json` の `deny` も常に優先されます。
+> 詳細な手順と危険性は `scripts/hooks/README.md` を参照。
+
+## 撤去（アンインストール）
+
+采配くんの systemd 常駐を止めて、インストールしたユニットを削除します。
+
+```bash
+# まず何が消えるか確認する（何も変更しません）
+bash uninstall.sh --dry-run
+
+# 実行（確認プロンプトあり）
+bash uninstall.sh
+
+# 確認を省く場合
+bash uninstall.sh --yes
+```
+
+**仕組み**: インストーラは「自分が入れたユニット」を台帳 `~/.config/conductor/installed-units.txt` に記録します。`uninstall.sh` はその台帳を読んで消すため、ユニット名の形に依存せず、あなたが自作した無関係な `conductor-*.service` を巻き込みません。
+
+台帳が無い古い環境では、`conductor@*.service` と `conductor-*.service` を走査するフォールバックが働きます。この場合は自作ユニットを巻き込む可能性があるため、**必ず `--dry-run` で対象を確認してから**実行してください。
+
+**`uninstall.sh` が消さないもの**（必要なら手動で実施してください）:
+
+| 対象 | 消さない理由 | 手動で消す場合 |
+|------|-------------|---------------|
+| linger 設定 | 他のサービスでも使われ得るため | `loginctl disable-linger "$USER"` |
+| `~/.conductor.env` | 接続情報（秘密）を含むため | `rm ~/.conductor.env` |
+| npm パッケージ | パッケージ管理は利用者の領分 | `npm uninstall -g @tyhld/conductor` |
+
 ## 注意事項
 
 - `settings.json` の deny は cc2_guard.py の allow より**優先**されます（多重防御）。Hook が「安全」と判断しても settings の deny に引っかかればブロックされます。