joelclaw

joelclaw — CLI 与事件总线

joelclaw CLI 是整个 joelclaw 系统的主要操作接口：事件总线（Inngest）、网关、可观测性（OTEL）、Agent 循环、订阅等。它基于 @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 现在通过 CLI 能力注册表／适配器运行时运行，同时保留现有的命令 UX 和 JSON 信封。

部署

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

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 就是正确的唤醒目标。

Workload Rig

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 Pod 中运行 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／代码库模式（Agent 可浏览）：

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

Agent 运行时验证（ADR-0180）

端到端验证名册分派时，请使用以下精确冒烟测试：

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

预期信号：

• agent list 包含内置的 coder、designer、ops
• event 显示一条 Agent Task Run，其 status: COMPLETED
• 运行输出包含 {"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"

Agent 循环

# 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

对于大量涉及知识库或 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（提交知识库更改）
docs/ingest	→ docs-ingest（PDF/markdown → 向量存储）

记忆

事件驱动的 observation/reflect/promote 链已停用，不再注册。目前的归属如下：

层	当前路径
证据	运行时适配器生成不可变的已接受运行
操作记忆	一个收集器和一个语义工作进程，用于投影流式观察和反思
精选记忆	Brain .svx 页面
回忆	流式反思、流式观察和精选页面分别作为独立通道
原始历史	使用 joelclaw sessions search 明确下钻查询

Agent 循环

事件	流程
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，检查工作进程 Pod
“Unable to reach SDK URL”	集群无法连接到工作进程	重启工作进程，运行 joelclaw refresh
Loop 故事状态为 SKIPPED	worktree 中的测试／类型检查失败	检查尝试输出
运行卡在 RUNNING 状态	工作进程在步骤执行期间崩溃	joelclaw logs errors，重启工作进程
INNGEST_PORT 环境变量冲突	k8s 服务名为 inngest	服务名是 inngest-svc — 保持不变
部署时 Implement 步骤被终止	工作进程重启终止了正在执行的步骤	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. 直接编辑运行时数据库仅作为最后手段
   • 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
Gateway 源码	packages/gateway/
k8s 清单	k8s/
部署脚本	k8s/publish-system-bus-worker.sh
ADR	~/Vault/docs/decisions/
遥测	joelclaw otel（Typesense/ClickHouse 中的 otel_events）
持久化回执	相关已注册根目录中的 Brain .svx
Loop 尝试输出	/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 技能。重量级依赖必须延迟加载 — 顶层导入崩溃不可接受。