# Parliament（议会）快速上手

密码串派生 Realm → 登录夺主席 / 加入席位 → 常驻服务密封同步共享上下文。
主席是用户入口；成员席位在本机干活并用 `parliament_note` 通报进度。

## 一次性初始化

```bash
# 交互输入密码，或事先 export CST_REALM_PASSWORD=…
cst-agent --realm-password-init
```

磁盘只存 salt + 公钥，**不存私钥**。

## 日常：登录夺主席，或加入席位

```bash
export CST_INSTANCE_ID=laptop-a   # 可选；默认用本机 hostname
cst-agent --login --realm-label "thinkpad"
# 其他机器（同 salt/公钥 + 密码）：
cst-agent --join --instance phone-b --realm-label "pixel"
# TUI: /realm login（夺主席）或 /realm join（不抢主席）
```

跨网段（如 Tailscale）多播发现不可用时，在 Realm 目录放 `peers.json`：

```json
{"peers":[{"host":"100.64.0.13","port":9100,"iid":"labpc","name":"labpc"}]}
```

效果：

1. 用密码解锁 Realm；`--login` / `/realm login` 使本机成为**唯一主席**
2. `--join` / `/realm join` 只登记席位票：主席空缺时才夺椅，否则以 **member** 身份加入
3. 写入本地登录票（24h；成员票在主席易主后仍有效，除非本席被剥夺主席）
4. 拉起后台议会服务（发现 + 密封通道按 revision 同步 `parliament.context`；
   Unix 下 accept 独立线程，dial 失败会指数退避，避免饿死入站）

查看状态：

```bash
cst-agent          # TUI: /status 或 /realm
# /realm login|join|stop
cst-agent --service-stop
```

### 常驻服务（推荐）

登录后会 fork 后台席位进程；也可用 systemd --user 托管前台循环（崩溃自动拉起）：

```bash
# 安装脚本附带的辅助命令
cst-agent-service install-unit
# 在 ~/.config/cst-agent/parliament.env 写入：
#   CST_REALM_PASSWORD=…
#   CST_INSTANCE_ID=my-laptop
systemctl --user enable --now cst-agent-parliament.service
cst-agent-service status
```

或手动前台：`CST_REALM_PASSWORD=… cst-agent --service-fg`。

## 单机默认（solo）

未设置 `collaboration` 时，**即使存在密码 Realm，默认也是单机 solo**：`task` /
`worker_*` / runtime jobs 可用，不强制登录闸。密码 Realm 仅保管密钥，不再自动开议会。

要进入议会模式，任选其一：

- `CST_COLLABORATION=parliament` 或 `settings.json` 里 `"collaboration": "parliament"`
- 已有 open 状态的 parliament meta（例如刚 `--login` 过）

显式议会模式下打开 agent 才要求登录（TTY 下可当场输入密码）。强制恢复本机 worker：
`CST_COLLABORATION=legacy_workers`。

## 议员协作协议

席位通过共享 `parliament.context` 协作（不是进程内 `task`/`worker_*`）：

1. 开工前阅读 Environment 里的 Shared parliament context
2. 用本机工具完成分配切片
3. 跨席相关的进度/议程/结果用工具 **`parliament_note`** 发布（`kind=status|agenda|result|handover`）
4. 服务在写入后尽快 dial peers；回合内若 revision 变化，会注入 `[cst] Parliament shared context updated`

显式 `"collaboration": "parliament"`（或 env）时：

- **硬禁用** `task` / `worker_*` / runtime 委托工具
- 提供 `parliament_note`；提示词说明 chair / member 角色合同

## 换项目（清场）

```bash
cst-agent --new-project my-app
```

清空共享上下文、撤销主席与登录票，并停止本机服务。Realm 密钥保留。

## 传输安全

Peer 在 Realm 证书互鉴后做 **临时 X25519 密钥交换**，后续议会上下文同步走
**XChaCha20-Poly1305**（Monocypher，无需 OpenSSL）。握手前的发现/证书交换仍是明文元数据。

## Docker 冒烟

```bash
bash scripts/docker_parliament_test.sh
```

Alpine 内构建，chair↔member 握手 + 密封通道同步（`sealed=1` / `peer_sync`）。

## 相关标志

| 标志 | 作用 |
|------|------|
| `--realm-password-init` | 创建密码 Realm |
| `--login` | 登录 + 夺主席 + 启服务 |
| `--join` | 加入席位（不抢主席）+ 启服务 |
| `--service` / `--service-fg` | 仅启服务 |
| `--service-stop` | 停服务 |
| `--new-project ID` | 清场换项目 |
| `--peer-port N` | 登录/服务用的 TCP 端口（默认 9100） |
| `--instance ID` | 实例 id（也可用 `CST_INSTANCE_ID`；默认 hostname） |