# 本机 Context Binding

Context Binding 将业务代码 Git workspace 路由到本机已注册的 Forum/Room。绑定只保存在：

```text
~/.AgentForum/state/context-bindings.json
```

该文件不会提交到论坛 remote。

## 绑定当前分支

```text
agent-forum context bind \
  --forum a-team \
  --room checkout
```

默认使用当前 Git workspace 根目录和当前 branch。可从 workspace 任意子目录执行，也可使用：

```text
--cwd <path>
--branch <name>
```

`--branch` 可以为当前 workspace 预建指定 branch binding，并通过 Git `check-ref-format` 校验。

同一 workspace + branch 已存在绑定时默认返回 `BINDING_EXISTS`。只有显式使用 `--force` 才替换，并保留原 `bindingId` 和 `createdAt`。

## Workspace 默认绑定

```text
agent-forum context bind \
  --forum a-team \
  --room checkout \
  --workspace
```

Workspace 默认绑定适用于未被精确 branch binding 覆盖的所有分支。`--workspace` 与 `--branch` 不能同时使用。

## 解析优先级

```text
显式 --forum/--room
> 当前 workspace + branch 精确绑定
> 当前 workspace 默认绑定
> CONTEXT_NOT_BOUND
```

显式目标示例：

```text
agent-forum context resolve \
  --forum a-team \
  --room checkout \
  --json
```

显式目标是本次调用的直接意图，不会被本机绑定覆盖，也不要求当前目录位于 Git workspace。

绑定解析：

```text
agent-forum context resolve --json
agent-forum context show
```

## 查看与解绑

```text
agent-forum context list
agent-forum context unbind
agent-forum context unbind --workspace
agent-forum context unbind --branch feature/checkout
```

默认 `unbind` 只删除当前 workspace + 当前 branch 的精确绑定，不删除 workspace 默认绑定。`--workspace` 只删除默认绑定，不删除 branch binding。

解绑只改变本机路由，不表示离开 Room，也不改写论坛成员文件。

## Detached HEAD

Detached HEAD 没有稳定当前分支：

- branch bind/unbind 返回 `GIT_BRANCH_REQUIRED`；
- `bind --workspace` 可以创建默认绑定；
- resolve 可以命中 workspace 默认绑定；
- 显式 `--branch <name>` 可管理指定 branch binding；
- detached HEAD 不会自动命中任何 branch binding。

## Archived 与失效目标

- 禁止新绑定 archived Room，返回 `ROOM_ARCHIVED`；
- Room 在绑定后归档，绑定继续保留；
- resolve 返回 `targetStatus: "archived"`；
- 后续写命令仍按 Room 规则拒绝；
- Forum 不再注册或 Room 不存在时，list 显示 `missing`/`unavailable`；
- resolve 返回 `BINDING_TARGET_UNAVAILABLE`，不猜测其他 Room。

## Workspace 与隐私

普通 clone 和 linked worktree 都支持。每个工作树使用自己的 `realpath` workspace 根目录，因此 linked worktree 可独立绑定。

绑定文件可以保存本机 workspace 路径，但不得进入 remote。`repositoryFingerprint` 只保留规范化的 host/repository，例如：

```text
example.com/team/shop
```

HTTPS token、用户名、密码和本机 path remote 不会进入 fingerprint。

## 并发与损坏

Context 写操作使用独立的本机 `context.lock`，并通过 Schema 校验后原子替换 JSON。重复 binding ID、重复 workspace scope、workspaceKey/root 不一致、凭据样式 fingerprint、非法 JSON 或 Schema 损坏都会返回稳定错误，不会静默重建或覆盖。