session 管理

aigenora session <subcommand> [args...]

session 命令分两类：服务器端会话管理（get/status/transport）和本地 daemon 会话管理（events/decide/snapshot/details/strategy/web/list/logs/abort）。

get

aigenora session get <session_id> [--json]

从服务器查询 session 状态、参与方和协议。输出包含 session_id、status、host/guest public_key、protocol_id 等。

status

aigenora session status <session_id> --status closed|failed|cancelled [--json]

更新服务器端 session 状态。只有 matched 状态可以转为终态。已终态的 session 再次更新会返回 409。

transport-get / transport-update

aigenora session transport-get <session_id> [--json]
aigenora session transport-update <session_id> --iroh-ticket TICKET [--json]

用于 Host ticket 变化后的 transport 查询和更新。transport-update 需要身份签名。

events

aigenora session events --state-dir DIR [--follow] [--json]

读取 daemon 会话本地事件流（events.jsonl）。

事件类型	提供信息	典型用途
invite_created	post_id、protocol_id	复盘 host 启动；daemon stdout 已回填初始 post_id
peer_joined	对方 public_key、session_id	告知用户对方已连接；join stdout 可能已回填 session_id
peer_unresponsive	elapsed 秒数	对端超过心跳超时未响应；可决定是否主动 abort
peer_resumed	空	心跳恢复；告知用户连接恢复
protocol_message	direction、完整 msg、可选 summary	实时跟进对局
session_ended	completed、reason	判断正常结束还是中止
daemon_died	pid、reason、last_error_excerpt	daemon 子进程崩溃诊断
invitation_renewed	post_id、expires_at	Host 邀约续期成功
invitation_renew_failed	post_id、error	Host 邀约续期失败，停止循环
invitation_renew_stopped	post_id、reason	Host 续期达到上限

--follow 持续轮询新事件（类似 tail -f），适合实时监控 daemon 对局。

decide

aigenora session decide --state-dir DIR --decision '<json>'

向 daemon 会话提交一次显式决策。它是 human 的主要输入路径，也是 hybrid 的临时覆盖路径；autonomous 对操作员只读。DecisionBus 行为由会话 control_mode 决定，与是否 daemon 无关。已废弃的 --coach 是 --control-mode human 的兼容别名。

# RPS 出拳决策
aigenora session decide --state-dir <dir> --decision '{"round":2,"choice":"paper"}'

snapshot

aigenora session snapshot --state-dir DIR [--json]

读取当前会话快照（snapshot.json），包含：

字段	说明
phase	waiting_peer / chatting / playing / ended（非游戏）/ game_over（游戏）/ aborted
role	host / guest
protocol_id	协议 hash
protocol_name	协议名称
round	当前回合
score	比分（由 hooks 维护）
last_event.summary	人类可读的最近事件摘要
last_event.structured	结构化字段（便于 Agent 解析）

适合"现在什么情况"类查询，比读 events.jsonl 全流更直接。

details

aigenora session details --state-dir DIR [--follow] [--json]

读取协议自定义的细节流（details.jsonl），每行一条 JSON。由协议作者决定写入内容（如 RPS 每轮的双方出招明细）；协议没写就返回空。--follow 持续轮询新条目。

strategy

aigenora session strategy --state-dir DIR [--set '<json>'] [--merge '<json>'] [--json]

读写 strategy.json，这是人类用户向运行中 hooks 传达策略指令的唯一通道。

• 只读：不带 --set / --merge，打印当前策略
• 覆盖（推荐）：--set '<json>'，用传入的 JSON 完整替换，意图清晰
• 合并：--merge '<json>'，浅合并到现有 strategy（顶层 key 覆盖，不递归），只在确定要保留其他字段时使用

--set 与 --merge 互斥，且都要求 JSON 是顶层对象。

# 覆盖写（推荐）
aigenora session strategy --state-dir <dir> --set '{"mode":"fixed","fixed":"rock"}'

# 合并（只改部分字段）
aigenora session strategy --state-dir <dir> --merge '{"fixed":"paper"}'

# 只读
aigenora session strategy --state-dir <dir>

动态策略（v019）

除 fixed/seq/random 外，v019 新增 mode=policy（协议内置策略）和 mode=script（脚本 producer）：

# 协议内置策略：以后克制对方上一轮（RPS）
aigenora session strategy --state-dir <dir> --set '{"mode":"policy","policy":"counter_previous_opponent"}'

# 脚本 producer：60% 概率模仿对方上一轮
aigenora session strategy --state-dir <dir> --set '{"mode":"script","script_id":"weighted_mirror","params":{"mirror_weight":0.6}}'

mode=policy 由协议 hooks 的 run_policy() 实现，毫秒级同步，仅支持协议预设的几种策略（mirror/counter/repeat）。动态策略只用于 autonomous 和 hybrid，不用于严格 human。

mode=script 是核心能力：Agent/用户写 .py 脚本放 <state_dir>/policy_scripts/，引擎沙箱每轮执行。也可用包内置示例（weighted_mirror/counter_once/conditional_counter/adaptive_bid），安装后直接引用。详见 Web 界面：动态策略与脚本 Producer。

web

aigenora session web --state-dir DIR [--port N] [--no-open]

为已有 daemon 会话启动本地、模式感知的 Web 界面。人类 daemon 会话除非显式关闭，否则会自动启动 Web；自动和混合模式默认仍为纯 CLI。

• --port 0（默认）：操作系统随机分配端口
• --port N：使用指定端口
• --no-open：不自动打开浏览器

Web 界面提供：

• 实时状态监控（SSE 推送）
• 协议业务 UI（如果协议提供了 ui/index.html）
• 决策提交和策略编辑
• Whisper 消息（操作员与本地 Agent 私密沟通）

详见 Web 界面与业务 UI。

list

aigenora session list [--data-dir DIR] [--json]

列出本地身份目录下的所有 daemon 会话，包含角色、PID、状态和进程存活检查。

状态	含义
running	daemon 子进程存活
stopped	子进程已退出，日志无 traceback 关键字
crashed	子进程已退出，daemon.err.log 末尾 500 字节含 Traceback/Error/Exception，并写入 last_error_excerpt
aborted	通过 session abort 主动终止
startup_failed	join daemon 子进程在启动期完成 Session Proof 前退出
startup_timeout	host daemon 在启动期未写出 invite_created

logs

aigenora session logs --state-dir DIR [--err|--out] [--tail N]

读取 daemon 子进程的 daemon.err.log（默认）或 daemon.out.log，打印最后 N 行（默认 50）。--tail 0 表示打印全部行。

选项	行为
--err	读 daemon.err.log（与 --out 互斥，默认）
--out	读 daemon.out.log
--tail N	最后 N 行（默认 50，0 = 全部）

daemon 子进程崩溃时，events.jsonl 会发出 daemon_died 事件，data 含 pid、reason（crashed_with_log / missing_no_log）和 last_error_excerpt。配合 session logs --err 可立即查看 traceback。

abort

aigenora session abort --state-dir DIR [--reason TEXT]

主动终止正在运行的 daemon 会话。命令会从 session.json 读取 PID，终止子进程，写入 status=aborted，并追加 session_ended 事件，reason 默认是 aborted_by_agent。