joelclaw

joelclaw — CLI とイベントバス

joelclaw CLI は、イベントバス（Inngest）、ゲートウェイ、オブザーバビリティ（OTEL）、エージェントループ、サブスクリプションなど、joelclaw システム全体を操作するための主要なインターフェースです。@effect/cli で構築され、HATEOAS JSON エンベロープを返します。

CLI がクラッシュした場合、それが最優先で修正すべき問題です。

バイナリ：~/.bun/bin/joelclaw ソース：~/Code/joelhooks/joelclaw/packages/cli/ ビルド：bun build packages/cli/src/cli.ts --compile --outfile ~/.bun/bin/joelclaw

アーキテクチャ

┌─ Colima VM (VZ framework, aarch64) ────────────────────────────────┐
│  Talos v1.12.4 → k8s v1.35.0 (single node, namespace: joelclaw)  │
│                                                                     │
│  inngest-0             StatefulSet   ports 8288 (API), 8289 (dash) │
│  redis-0               StatefulSet   port 6379                     │
│  typesense-0           StatefulSet   port 8108                     │
│  restate-0             StatefulSet   ports 8080, 9070, 9071        │
│  system-bus-worker     Deployment    port 3111 (110+ functions)    │
│  restate-worker        Deployment    port 9080                     │
│  dkron-0               StatefulSet   port 8080                     │
│  minio-0               StatefulSet   ports 9000, 9001              │
│  docs-api              Deployment    port 3838                     │
│  livekit-server        Deployment    ports 7880, 7881              │
│  bluesky-pds           Deployment    port 3000                     │
│                                                                     │
│  ⚠️ Inngest service named inngest-svc (not inngest)                │
│     k8s auto-injects INNGEST_PORT env collision otherwise          │
└─────────────────────────────────────────────────────────────────────┘
        ↕ NodePort on localhost

Gateway daemon (always-on pi session, Redis event bridge)
NAS "three-body" (ASUSTOR, 10GbE NFS, 64TB RAID5 + NVMe cache)
Vault ~/Vault (Obsidian, PARA method — ADRs, system log, contacts)

Inngest イベントキー：INNGEST_EVENT_KEY から読み取ります。古い開発用キーをハードコードしないでください。 k8s マニフェスト：~/Code/joelhooks/joelclaw/k8s/

CLI コマンドリファレンス

ヘルスとステータス

joelclaw status                            # Health: server + worker + k8s pods
joelclaw jobs status                       # Unified runtime workload snapshot (queue + Restate + Dkron + Inngest)
joelclaw inngest status                    # Inngest server details
joelclaw functions                         # List all 110+ registered functions
joelclaw refresh                           # Force re-register with Inngest server

イベントの送信

joelclaw send "event/name" --data '{"key":"value"}'
joelclaw send "pipeline/video.requested" --data '{"url":"https://youtube.com/watch?v=XXX"}'
joelclaw send "agent/story.start" --data '{"prdPath":"/abs/path/prd.json","storyId":"S-1"}'

実行の表示

joelclaw runs                              # Recent 10
joelclaw runs --count 20 --hours 24        # More runs, wider window
joelclaw runs --status FAILED              # Just failures
joelclaw run <RUN_ID>                      # Step trace + errors for one run

イベントの表示

joelclaw events                            # Last 4 hours
joelclaw events --prefix memory/ --hours 24
joelclaw events --prefix agent/ --hours 24
joelclaw events --count 50 --hours 48

ログ

joelclaw logs                              # Worker stdout (default 30 lines)
joelclaw logs errors                       # Worker stderr (stack traces)
joelclaw logs server                       # Inngest k8s pod logs
joelclaw logs server -n 50 --grep error    # Filtered server errors
joelclaw logs worker --grep "observe"      # Grep worker logs

永続的なレシートとテレメトリー

従来の joelclaw log write / slog JSONL ジャーナルは廃止されました。joelclaw otel で構造化されたランタイムテレメトリーを出力・クエリし、Brain .svx に永続的な意思決定と変更レシートを記録してください。joelclaw logs は引き続きランタイムログの読み取り・分析に使用します。

シークレット

joelclaw secrets status
joelclaw secrets lease <name> --ttl 15m
joelclaw secrets revoke <lease-id>
# Revoke only the exact leases acquired by this task.
joelclaw secrets audit --tail 50
joelclaw secrets env --dry-run

通知

joelclaw notify send "Worker restarted and healthy" --kind receipt
joelclaw notify send "Immediate action required" --kind alert

--priority は、互換性のためのメタデータとして非推奨になっています。--kind を使用してください。配信はバージョン管理されたルーティングテーブルが制御します。

ケイパビリティアダプターのパス（ADR-0169 フェーズ 4）

mail、otel、recall、subscribe は、既存のコマンド UX と JSON エンベロープを維持しながら、CLI ケイパビリティレジストリー／アダプターランタイムを通じて実行されるようになりました。

デプロイ

joelclaw deploy worker                              # dry-run deploy plan
joelclaw deploy worker --restart --execute         # execute worker sync deployment
joelclaw deploy worker --restart --execute --force # force with active runs (disruptive)

修復

joelclaw heal list
joelclaw heal run RUN_FAILED --phase fix --context '{"run-id":"01ABC"}'           # dry-run
joelclaw heal run RUN_FAILED --phase fix --context '{"run-id":"01ABC"}' --execute # execute

ゲートウェイ

joelclaw gateway status                    # Gateway health + session info
joelclaw gateway events                    # Recent gateway events
joelclaw gateway test                      # Send test message through gateway
joelclaw gateway restart                   # Restart gateway daemon
joelclaw gateway stream                    # Live stream gateway events

オブザーバー

observer は、joelclaw の正規の Observer ターゲットです。デフォルトの Herdr セッションからペインを推測したり、隠れた特例として扱ったりしないでください。まず CLI で解決して管理します。

joelclaw observer status                   # Herdr protocol + Observer registry/session metadata
joelclaw observer resolve observer         # Canonical target → named Herdr session + pane
joelclaw observer resolve dispatcher       # Dispatcher pane in the Observer family
joelclaw observer cycle                    # Dry-run safe named-session cycle plan
joelclaw observer cycle --execute          # Cycle only the named observer Herdr server, then rotate Observer

Observer のスケジュール設定や起動の前に、joelclaw observer resolve observer を使用してください。OBSERVER_TARGET_UNHEALTHY で失敗した場合は、joelclaw observer status を実行してください。Herdr プロトコルにずれが生じている場合は、joelclaw observer cycle --execute を実行してください。resolve が正常な状態であれば、起動先には joelclaw wake ... --target observer を使用します。

ワークロードリグ

joelclaw workload plan "intent" --stages-from stages.json --write-plan plan.json
joelclaw workload run plan.json --stage <stage-id> --tool pi|codex|claude
joelclaw workload dispatch plan.json --to BlueFox --from MaroonReef --send-mail
joelclaw workload sandboxes list
joelclaw workload sandboxes cleanup --expired --dry-run
joelclaw workload sandboxes janitor

ランタイムの実態：

• workload run は Redis に登録され、その後 Restate が dagOrchestrator → dagWorker を通じてステージを実行します
• dagWorker のハンドラー：shell、infer、microvm
• infer は、マウントされた認証情報、スキル、アイデンティティを使い、k8s の restate-worker ポッド内で pi を実行するようになりました
• --stages-from は明示的なステージ DAG の入り口です。依存関係のゲートと循環検出が実際に機能します

pi での非同期ランタイム監視

読み込まれた pi 拡張機能 packages/pi-extensions/inngest-monitor/index.ts で、inngest_send / inngest_runs に加えて runtime_jobs_monitor が使えるようになりました。

ほかの作業をしながら、pi セッションに ADR-0217 ランタイム基盤の監視を続けさせたい場合に使用します。

• runtime_jobs_monitor {"action":"start","interval":5,"report":true} — joelclaw jobs status のバックグラウンドポーリングを開始します
• runtime_jobs_monitor {"action":"status"} — 最新のランタイムスナップショットを確認します
• runtime_jobs_monitor {"action":"stop"} — ポーラーを停止し、最後のフォローアップ要約を送信します

ウィジェットでは、まずランタイムのヘルス（キュー／Restate／Dkron／Inngest）が表示され、その下に追跡中の Inngest 実行が表示されます。重大度の変化と、意味のあるワークロード状態の変化は OTEL と、非同期の結果報告のための非表示のフォローアップメッセージを出力します。そのため、正常であっても保留状態になったバックログが通知されないままになることはありません。

オブザーバビリティ（OTEL）

joelclaw otel list --hours 1               # Recent telemetry events
joelclaw otel search "error" --hours 24    # Search OTEL events
joelclaw otel stats --hours 24             # Aggregate stats
joelclaw otel emit "action.name" --source codex --component agent-loop --success  # Emit event

システムのナレッジ（ADR-0199）

joelclaw knowledge search "query"          # Search system knowledge
joelclaw knowledge search "query" --type adr  # Filter by type (adr|skill|lesson|pattern|retro|failed_target)
joelclaw knowledge sync                    # Re-index ADRs + skills from filesystem
joelclaw knowledge clear-failed <target>   # Clear resolved failed targets

Brain／コードベースのパターン（エージェントが閲覧可能）：

ls ~/Vault/system/brain/codebase/          # List established patterns
cat ~/Vault/system/brain/codebase/<name>.md  # Read a specific pattern

サブスクリプション（ADR-0127）

joelclaw subscribe list                    # All feed subscriptions
joelclaw subscribe add <url> [--name N]    # Add a feed
joelclaw subscribe remove <url>            # Remove a feed
joelclaw subscribe check [--url URL]       # Check feeds for new items
joelclaw subscribe summary                 # Summary of recent items

エージェントランタイムの検証（ADR-0180）

ロスターのディスパッチをエンドツーエンドで検証する際は、次のスモークテストをそのまま使用してください。

joelclaw agent list
joelclaw agent run coder "reply with OK" --timeout 20
joelclaw event <event-id>

期待されるシグナル：

• agent list に組み込みの coder、designer、ops が含まれている
• event に status: COMPLETED の Agent Task Run が1つ表示される
• 実行出力に {"status":"completed", ...} が含まれている

失敗時の対応：

• Unknown agent roster entry: coder はプロンプトの失敗ではなく、ランタイムの不整合を意味します。
  • 最新の system-bus-worker をデプロイします
  • ホストのワーカープロセスを再起動します
  • 同じ3ステップのスモークテストを再実行します
• Inngest API に接続できない場合（localhost:8288）、まずローカルのコントロールプレーン（Colima/Talos）を復旧してから、検証を再試行してください。

Brain による想起

joelclaw recall "query about past context"  # Search disposable Brain + observation projections

Brain の .svx ページが引き続き正規の情報源です。Typesense の observations コレクションと brain_graph_nodes コレクションは再構築可能な投影であり、別のメモリストアではありません。

検出

joelclaw discover "https://example.com" --context "why this is interesting"

エージェントループ

# Start a loop
joelclaw loop start --project ~/Code/joelhooks/joelclaw \
  --goal "Implement feature X" \
  --context ~/Vault/docs/decisions/0XXX.md \
  --max-retries 2

# Start with existing PRD
joelclaw loop start --project PATH --prd prd.json --max-retries 2

# Monitor
joelclaw loop status <LOOP_ID>
joelclaw loop status <LOOP_ID> -c          # Compact: one line per story
joelclaw loop status <LOOP_ID> -v          # Verbose: criteria, output paths
joelclaw watch <LOOP_ID>                   # Live: polls 15s, exits on completion
joelclaw watch                             # Auto-detects active loop

# Management
joelclaw loop list                         # All loops in Redis
joelclaw loop cancel <LOOP_ID>             # Stop + cleanup
joelclaw loop nuke dead                    # Remove completed loops from Redis

その他のコマンド

joelclaw sleep [on|off|status]             # Sleep mode for gateway
joelclaw note <text>                       # Quick note to Vault
joelclaw vault read <ref>                  # Resolve/read ADR/project/path refs
joelclaw vault search <query>              # Search vault markdown
joelclaw vault adr list                    # ADR inventory (optionally by status)
joelclaw vault adr collisions              # ADR number collision report
joelclaw vault adr audit                   # ADR health + collision + index checks
joelclaw vault adr rank                            # ADR NRC+novelty ranking
joelclaw skills audit [--deep]             # On-demand skill garden report
joelclaw search <query>                    # Full-text search
joelclaw email [scan|triage]               # Email operations
joelclaw x [post|mentions]                 # X/Twitter operations
joelclaw nas [status|health]               # NAS operations
joelclaw diagnose <topic>                  # System diagnosis
joelclaw usage [--source router|agents|all] # Token usage + cost from ClickHouse
joelclaw deploy worker [--restart] [--execute]
joelclaw heal [list|run]
joelclaw inngest sync-worker [--restart]   # Worker lifecycle

Vault を多用するタスクや ADR の整備には、専用の vault スキルを使用してください。

出力モード

ほとんどのコマンドは、プレーンテキスト出力用の --compact/-c に対応しています。監視には compact を使用してください。 JSON（デフォルト）では、next_actions を含む HATEOAS エンベロープが返されます。

ストーリーパイプライン（ADR-0155）

3段階のパイプラインです：実装 → 検証 → 判定。各ストーリーは Inngest の耐障害性を備えた実行で各段階を進みます。

# Fire a single story
joelclaw send agent/story.start -d '{
  "prdPath": "/Users/joel/Code/joelhooks/joelclaw/prd.json",
  "storyId": "CFP-2"
}'
# ⚠️ ALWAYS use absolute path for prdPath — worker CWD is packages/system-bus/

PRD 形式（Zod による検証）：

{
  "name": "Project Name",
  "context": {},
  "stories": [
    {
      "id": "STORY-1",
      "title": "What to build",
      "description": "Details",
      "priority": 1,
      "acceptance": ["criterion 1", "criterion 2"],
      "files": ["path/to/relevant/file.ts"]
    }
  ]
}

重要：

• context は {} またはオブジェクトである必要があります。null または文字列は絶対に指定しないでください
• 各ストーリーには priority（数値）が必要です
• Inngest 関数で retries: 0 を絶対に設定しないでください。再起動時の安全性が損なわれます（ADR-0156）

イベントの種類

パイプライン

イベント	チェーン
pipeline/video.requested	→ video-download → transcript-process → content-summarize
pipeline/video.download	pipeline/video.requested のレガシーエイリアス
pipeline/transcript.requested	→ transcript-process → content-summarize
pipeline/transcript.process	pipeline/transcript.requested のレガシーエイリアス
content/summarize.requested	→ content-summarize
content/summarize	content/summarize.requested のレガシーエイリアス
content/updated	→ content-sync（Vault の変更を Git にコミット）
docs/ingest	→ docs-ingest（PDF/Markdown → ベクトルストア）

メモリ

イベント駆動型の観察／リフレクト／昇格チェーンは廃止され、登録されていません。現在の管理体制は次のとおりです。

レイヤー	現在の経路
エビデンス	ランタイムアダプターが不変の承認済み Runs を生成
運用メモリ	1つのコレクターと1つのセマンティックワーカーが、流入する観察とリフレクションを投影
キュレーション済みメモリ	Brain の .svx ページ
想起	流入するリフレクション、流入する観察、キュレーション済みページをそれぞれ別のレーンとして扱う
生の履歴	joelclaw sessions search による明示的な詳細検索

エージェントループ

イベント	フロー
agent/story.start	→ story-pipeline（実装 → 検証 → 判定）
agent/loop.started	→ 計画 → ストーリーパイプライン → 完了
agent/loop.story.passed	→ 計画（次のストーリー）
agent/loop.story.failed	→ 計画（再試行または次のストーリー）
agent/loop.completed	→ 完了（マージバック＋クリーンアップ）

ゲートウェイとチャネル

イベント	目的
gateway/message.received	任意のチャネルからの受信メッセージ
gateway/heartbeat	ゲートウェイのヘルスチェック ping
channel/telegram.callback	Telegram のコールバッククエリ

サブスクリプションと検出

イベント	目的
discovery/noted	URL／アイデアを記録 → エンリッチメントパイプライン
subscriptions/check	フィードをポーリングして新しい項目を確認

システムとスケジュール実行

イベント	目的
system/log	システムログエントリー
system/health.check	スケジュールされたヘルスモニタリング
cron/daily-digest	朝のダイジェスト生成
cron/check-email	定期的なメールスキャン
cron/check-calendar	カレンダーの確認
cron/nightly-maintenance	Typesense とシステムのメンテナンス

通知

イベント	ソース
webhook/github	GitHub の Webhook イベント
webhook/vercel	Vercel のデプロイイベント
webhook/todoist	Todoist の Webhook イベント
webhook/front	Front の Webhook イベント

失敗した実行のデバッグ

joelclaw runs --status FAILED              # 1. Find the failure
joelclaw run <RUN_ID>                      # 2. Step trace + inline errors
joelclaw logs errors                       # 3. Worker stderr
joelclaw logs server --grep error          # 4. Inngest server errors
joelclaw otel search "error" --hours 1     # 5. OTEL telemetry

よくある失敗パターン

症状	原因	対処方法
イベントは受け付けられるが、関数が実行されない	Inngest からワーカーにアクセスできない	joelclaw refresh を実行し、ワーカーポッドを確認します
「Unable to reach SDK URL」	クラスターからワーカーにアクセスできない	ワーカーを再起動し、joelclaw refresh を実行します
ループストーリーが SKIPPED になる	ワークツリーでテストまたは型チェックに失敗した	試行の出力を確認します
実行が RUNNING のまま止まる	ステップの途中でワーカーがクラッシュした	joelclaw logs errors を実行し、ワーカーを再起動します
INNGEST_PORT 環境変数の衝突	k8s サービス名が inngest である	サービス名は inngest-svc です。この設定を維持してください
デプロイ時に実装ステップが強制終了する	ワーカーの再起動により実行中のステップが強制終了した	ADR-0156：retries: 2 により、この問題を乗り越えられます

RUNNING のまま残った実行の調査（SDK に到達できないゴースト）

joelclaw runs --status RUNNING に、解消されない古いヘルスジョブが表示される場合：

1. まずオペレーターコマンドを使用します
   • プレビュー：joelclaw inngest sweep-stale-runs
   • 適用（バックアップ＋トランザクション）：joelclaw inngest sweep-stale-runs --apply
2. 症状の種類を検証します
   • joelclaw run <run-id>
   • Unable to reach SDK URL または EOF writing request to SDK を含むトレース／ファイナライズエラーを探します。
3. 一覧と詳細の不一致は、既知のマスク問題として扱います
   • runs の一覧には古いメタデータが表示される場合があります。
   • run の詳細とトレース／履歴が信頼できる情報源です。
4. ランタイムの DB を直接編集するのは、最後の手段に限ります
   • Inngest の状態は k8s StatefulSet PVC の inngest-0:/data/main.db にあります。
   • まずバックアップします：kubectl -n joelclaw exec inngest-0 -- sqlite3 /data/main.db '.backup /data/main.db.pre-sweep-<ts>.sqlite'。
5. 部分的な編集ではなく、完全な契約に従って古い実行を終端状態にします
   • 古い実行について、欠落している history.type='FunctionCancelled' を挿入します。
   • function_finishes 行が存在することを確認します。
   • その後、古い候補の trace_runs.status=500（キャンセル済み）を設定します。
6. 変更後に検証します
   • joelclaw run <run-id> で終端状態が確認できるはずです。
   • joelclaw runs --status RUNNING には、実際にアクティブな実行のみが表示されるはずです。

ポイントインタイムバックアップを作成せずに main.db を変更してはいけません。

ワーカーの変更をデプロイする

公開スクリプトを使用します。ビルド、プッシュ、k8s の適用、ロールアウトを処理します：

~/Code/joelhooks/joelclaw/k8s/publish-system-bus-worker.sh

デプロイワークフローの詳細については、sync-system-bus スキルを参照してください。

主なパス

対象	パス
CLI のソース	packages/cli/src/
CLI コマンド	packages/cli/src/commands/
CLI バイナリ	~/.bun/bin/joelclaw
ワーカーのソース	packages/system-bus/
Inngest 関数	packages/system-bus/src/inngest/functions/
関数インデックス（ホスト）	packages/system-bus/src/inngest/functions/index.host.ts
関数インデックス（クラスター）	packages/system-bus/src/inngest/functions/index.cluster.ts
推論ユーティリティ	packages/system-bus/src/lib/inference.ts
ゲートウェイのソース	packages/gateway/
k8s マニフェスト	k8s/
デプロイスクリプト	k8s/publish-system-bus-worker.sh
ADR	~/Vault/docs/decisions/
テレメトリ	joelclaw otel（Typesense/ClickHouse の otel_events）
永続レシート	該当する登録済みルート内の Brain .svx
ループ試行の出力	/tmp/agent-loop/{loopId}/{storyId}-{attempt}.out

CLI のビルド

cd ~/Code/joelhooks/joelclaw
bun build packages/cli/src/cli.ts --compile --outfile ~/.bun/bin/joelclaw

変更のたびにテストを実行してください：

joelclaw status
joelclaw send --help
joelclaw runs --count 1

CLI コマンドは packages/cli/src/commands/ にあり、コマンドごとにファイルが分かれています。cli-design スキルに従ってください。依存関係の重いパッケージは遅延読み込みにする必要があります。トップレベルのインポートによるクラッシュは許容されません。