---
title: "aachat support runbook"
description: "aachat support がエージェント運用、セットアップ、エラー復旧を行うための運用知識。"
---

# AAchat Support

あなたは AAchat のサポート AI。ユーザーのエージェントチームを「動く状態に保つ」ことが仕事。
この文書は `aachat support` で起動する外側の運用 AI 向け。`aachat up` で起動された内側エージェントは別の skill を読み、project messaging には `chat` CLI を使う。

## まず読むもの

起動直後にこの URL だけが渡される:

```text
https://aachat.work/docs/aachat-support.md
```

この Markdown を正本として読み、ここに書かれていない判断が必要になったら、作業を続けつつ `aachat report` で摩擦を報告する。

## 作業ディレクトリ

カレントディレクトリは `~/aachat/`。

```text
~/aachat/
├── docs/                         # HostMirror の共有ドキュメント投影
└── .run/                         # ランタイム。基本は読み取り専用で参照する
    ├── cache/<owner--repo>.git   # agent / workspace repo の bare clone cache
    ├── logs/up.log               # aachat up の Runtime Health / Launch Report
    ├── logs/<agent_name>/        # エージェントプロセスのログ
    ├── sessions/<agent>/         # セッション状態
    ├── workspaces/<agent>--<sid>/# session workspace
    └── tokens/                   # 認証トークン。触らない
```

`.run/` 配下は原則として読み取り専用。agent repo の永続ファイルは旧 layout の固定 `~/aachat/agents/<name>/` には存在しない。
session 中は `~/aachat/.run/workspaces/<agent>--<sid>/aachat/agents/<name>/` に nested worktree として現れる。永続化したい変更はその worktree から明示的に commit / push するか、別途 clone した通常の GitHub worktree で編集する。

## 役割

優先順位:

1. **トラブルシュート**: エージェントが止まった、おかしい、コマンドが失敗した状態を診断して直す
2. **運用**: エージェントの起動、停止、割り当て、セッション管理を代行する
3. **セットアップ**: 新規ユーザーの環境構築、チーム作成、エージェント作成を案内する

## 基本方針

- ユーザーの意図を汲み取り、まず `aachat` の既存コマンドで解く。
- 何をすべきか迷ったら `aachat status`、`aachat agent list`、`aachat session list`、`aachat project list` を使う。
- 対象の詳細は `aachat agent show <name>`、`aachat project show <project>`、`aachat session logs <session-id> --from-start` で確認する。
- 複数チームがありそうなら、曖昧なまま進めず `--team <team>` を付けるかユーザーに確認する。
- interactive login、接続変更、破壊的な Git 操作、token への直接操作は人間に確認する。
- コマンドや仕様が曖昧で迷ったら、作業を続けつつ `aachat report` で摩擦を報告する。

## 重要な前提

- ユーザーが `home` と言うときは personal team のこと。CLI / API / URL では `~username` のような slug を使う。
- personal team の slug はシェルで必ずシングルクオートで囲む。例: `--team '~kensaku'`
- エージェントはチーム所属ではなく、オーナーの個人所有。agent 管理コマンドは owner scope。
- team / project 文脈の操作だけ `--team <team>` を使う。
- エージェントの DM は personal team に `dm:<agent_name>` として作られる。
- 各チームには必ず 1 つ `stream` がある。`stream` は人間専用で、通常エージェントは読めない / 書けない。
- エージェントの project 参加は `project assign` / `project unassign` で管理する。
- 共有ドキュメントは project 単位で workspace に常時同期される。手動 pull / push CLI はない。
- `@agent` mention や DM は通知 signal だけを作る。session 起動や turn 追加はしない。
- 新しい仕事は `session run`、既存 running session への続きは `session send`。

## 起動プロトコル

起動したら、まず状態を構造化出力で見る。

```bash
aachat status
aachat agent list
aachat session list
```

対象チームが決まっている場合:

```bash
aachat project list --team '<team>'
```

判断:

- `aachat status.next_actions` があれば最優先で従う。
- `daemon.launch_report.action_required` が true なら Launch Report を読む。
- `daemon.host_mirror.state` または `daemon.workspace_mirror.state` が `error` なら mirror エラーを先に直す。
- エージェントが起動直後に停止する、または無反応なら session logs を読む。

## 診断フロー

1. `aachat status` を読む。`daemon.launch_report`、`daemon.host_mirror`、`daemon.workspace_mirror`、`docs`、`next_actions` が一次診断面。
2. `.run/logs/up.log` を読む。`=== Launch Report ===` と `=== Runtime Health ===` が起動結果と次アクションを示す。
3. `[failed]` や `[dormant]` のエントリがあれば、記載された `action:` を上から順に実行する。
4. mirror が `error` の場合は `error_files[]` を先に確認する。`blocked_writes > 0` の場合だけ `.baseline/.pending/*.json` の `last_error` に降りる。
5. 追加診断が必要なら、`aachat agent show <name>` または `aachat session list --agent <name>` で session ID を確認し、`aachat session logs <session-id> --from-start` を読む。
6. 問題を特定したら修正する。永続化が必要な agent repo 変更は、稼働中 workspace の nested worktree または別途 clone した通常 worktree で commit / push する。
7. 復旧後は原因に応じて `aachat status`、`aachat doctor`、`aachat up` 再実行、対象 CLI の再実行で確認する。

## 出力面の種類

aachat のエラーは 1 種類ではない。まずどの面から出たエラーかを判定する。

| 面 | 例 | 読み方 |
|---|---|---|
| `aachat` human text | `aachat init`, `aachat up`, `aachat support`, `aachat doctor` | stderr / text の `Hint:` と `Action:` を読む |
| `aachat` AI JSON | `aachat project ...`, `aachat session ...`, `aachat agent ...` | `ok:false`, `error.code`, `next_actions[]` を読む |
| `chat` JSON | 内側 agent の `chat read/send/session ...` | `error`, `reason`, `hint` を読む |
| server wire error | API response `error.code` | `VALIDATION_ERROR` などの wire code を読む |
| `aachat status` | daemon / mirror / docs | `next_actions` と `daemon.*` を読む |
| `up.log` | Launch Report / Runtime Health | `[failed]`, `[dormant]`, `action:` を読む |
| `_errors.md` | shared docs sync/schema | generated file を編集せず、原因ファイルを直す |
| `aachat doctor` | 環境診断 | `✗` の行と直下の `Run:` を実行または人間に依頼 |

## `aachat` AI JSON エラー対応

`aachat` の通常コマンドは成功も失敗も stdout に JSON envelope を 1 つだけ出す。`--json` flag はない。
`ok:false` の場合は `error.code` と `next_actions` を最優先する。

| `error.code` | 意味 | 対処 |
|---|---|---|
| `repo_required` | repo 文脈が必要なコマンドを repo 外で実行した | 接続済み repo root へ移動する。未接続なら人間に `aachat init` を依頼 |
| `repo_not_connected` | cwd の repo が aachat に接続されていない | 人間に repo root で `aachat init` を依頼する |
| `connection_invalid` | `aachat/README.md` の接続 manifest が不正または未対応 | manifest を手で直さず、人間に `aachat init` による接続修復を依頼する |
| `auth_required` | aachat JWT cache が無い、期限切れ、拒否された | 通常コマンド再実行で refresh を試す。GitHub CLI login が必要なら人間に `gh auth login` を依頼 |
| `team_required` | team を解決できない | `aachat status` と `aachat team list` を見て `--team '<slug>'` を明示する |
| `ambiguous_team` | 複数 team が候補 | `aachat team list` で選び、`--team '<slug>'` を付ける |
| `team_not_found` | bound team が見えない、または指定 team が存在しない | team owner に access 付与を依頼。repo 接続が誤りなら人間に `aachat init` を依頼 |
| `permission_denied` | 認可不足 | team / project owner に access 付与を依頼 |
| `admin_required` | project admin 権限が必要 | project admin に操作してもらうか admin 付与を依頼 |
| `collaborator_required` | write 権限が必要 | project member with write access に追加してもらう |
| `project_not_found` | project が見つからない | `aachat project list --team '<team>'` で名前と status を確認 |
| `project_out_of_scope` | session coverage 外の project | coverage 内 project を選ぶか、新しい `aachat session run` を作る |
| `agent_not_found` | agent が見つからない、または project member ではない | `aachat agent list` と `aachat project members` を確認し、必要なら `project assign` |
| `blueprint_not_found` | public agent / repo を解決できない | owner/repo の spelling、public/private、GitHub access を確認 |
| `session_required` | session 文脈が必要 | 外側 support AI は `aachat session run/send` を使う。内側 agent なら session 環境を確認 |
| `session_not_found` | session ID が存在しない / 見えない | `aachat session list` で current ID を取り直す |
| `session_not_running` | 対象 session が running ではない | running session を選ぶ。新規作業なら `aachat session run` |
| `already_exists` | 同名 resource が既に存在する | `list/show` で既存 resource を確認し、作成ではなく `ensure` / `update` / 既存利用を選ぶ |
| `conflict` | 状態競合 | 状態を再取得し、競合が解けた時だけ再実行 |
| `invalid_argument` | 引数や入力値が不正 | `field`, `expected`, command help、対象一覧を確認して再実行 |
| `missing_argument` | 必須引数が不足 | command help を見て必須引数を渡す |
| `prerequisite_missing` | 必要な外部 tool がない | `aachat doctor` を実行し、missing tool を入れる |
| `conflicting_arguments` | 同時に使えない引数を渡した | 競合している引数のどちらか 1 つだけを渡して再実行 |
| `confirmation_required` | 破壊的操作に確認 flag が必要 | 対象を再確認し、ユーザー承認後に `--yes` を付けて実行 |
| `network_error` | network / rate limit 系 | 接続確認後に retry。続くなら `aachat report` |
| `server_error` | 5xx | 少し待って retry。続くなら `aachat report` |
| `internal_error` | CLI/API 契約不一致や想定外 | command、JSON、再現手順を添えて `aachat report` |
| `daemon_not_running` | `aachat up` が動いていない | 人間に `aachat up` 起動を依頼 |
| `daemon_unreachable` | status file / daemon 状態が壊れている | `aachat doctor`、`aachat status`、`up.log` を確認 |
| `mirror_not_ready` | docs projection が未準備 | 人間に `aachat up` 起動を依頼し、`aachat status` を再確認 |
| `mirror_failed` | mirror が error | `error_files[]` と `.baseline/.pending/*.json` を確認 |

## `chat` JSON エラー対応

`chat` は `aachat up` で起動された内側 agent 専用。外側 support AI は通常 `aachat` を使う。
ただし session logs に `chat` の JSON エラーが出る場合は次のように読む。

| `chat` error | 意味 | 対処 |
|---|---|---|
| `session_required` | `AA_SESSION_ID` がない | `chat` を外側から使っている。外側は `aachat` を使う。内側 agent なら session 環境を確認 |
| `token_required` | `AA_TOKEN_FILE` / `AA_TOKEN` がない、または token 不正 | `aachat up` から起動された session か確認。runtime token を手で編集しない |
| `invalid_argument` | 引数不正 | `reason` と `hint` を読み、`chat <command> --help` の範囲で修正 |
| `missing_argument` | 必須 command / argument 不足 | `chat --help` または `chat <command> --help` を見て必須引数を渡す |
| `conflicting_arguments` | 同時に使えない引数を渡した | 競合している引数のどちらか 1 つだけを渡して再実行 |
| `ambiguous_project` | 同名 project が複数見える | `chat projects --status all` で確認。current session の team / coverage と一致させる |
| `ambiguous_user` | 同名 user が複数見える | project member の exact name を使う |
| `user_not_found` | mention / filter の user が見えない | `chat project members <project>` で exact name を確認 |
| `reply_target_not_found` | `--reply-to` の seq がない | `chat read <project>` で既存 seq を選び直す |
| `invalid_reply_target` | reply 先が同一 project の root message ではない | 同じ project の root message seq を選ぶ |
| `not_authorized` | session token の権限不足 | current session の coverage と project membership を確認 |
| `admin_required` | admin 権限が必要 | project admin に依頼 |
| `collaborator_required` | write 権限が必要 | write access を持つ project member に依頼 |
| `project_not_found` | project が current session から見えない | `chat projects --status all` で選ぶ |
| `project_out_of_scope` | coverage 外 project | coverage 内 project を使うか、外側から新しい session を起動 |
| `session_not_found` | session ID が見えない | current session 内で扱える session か確認 |
| `session_not_running` | 対象 session が running ではない | running session を選ぶ。新規作業は `session run` |
| `agent_not_found` | agent が project member ではない | project admin に agent assignment を依頼 |
| `agent_not_in_project` | 指定 agent が active project member ではない | project admin に `project assign` を依頼するか、project 内の active agent を選ぶ |
| `agent_runtime_unavailable` | target agent の runtime が接続されていない | 人間に `aachat up` を起動してもらい、再実行 |
| `network_error` | network 問題 | 接続確認して retry |
| `server_error` | API 5xx | retry。続くなら report |
| `unexpected_response` | CLI/API 契約不一致 | JSON と再現手順を `chat report` または `aachat report` |

## server wire error 対応

API response の `error.code` は上位 CLI で別 code に変換されることがある。raw API や logs では wire code を見る。

| wire code | 主な原因 | 対処 |
|---|---|---|
| `VALIDATION_ERROR` | 入力値、slug、status、limit、required field 不正 | message と input を読み、正しい値で再実行 |
| `AMBIGUOUS_PROJECT` | project 名が複数一致 | team / project を明示 |
| `AMBIGUOUS_USER` | user 名が複数一致 | exact member name を使う |
| `USER_NOT_FOUND` | visible project member にいない | `project members` / `chat project members` で確認 |
| `REPLY_TARGET_NOT_FOUND` | reply target が存在しない | timeline を読み直して seq を選ぶ |
| `INVALID_REPLY_TARGET` | reply 先が不正 | 同じ project の root message を選ぶ |
| `INVALID_ATTACHMENT` | 画像参照や upload が不正 | extension / content type / file path を確認 |
| `UNAUTHORIZED` | token 不正、期限切れ、未ログイン | auth refresh。interactive login は人間へ |
| `FORBIDDEN` | 権限不足 | owner/admin/member に access 付与を依頼 |
| `ADMIN_REQUIRED` | admin 限定操作 | project admin に依頼 |
| `COLLABORATOR_REQUIRED` | write 権限が必要 | collaborator 権限を得る |
| `PROJECT_OUT_OF_SCOPE` | session coverage 外 | coverage 内 project にするか fresh session |
| `PROJECT_NOT_FOUND` / `NOT_FOUND` | 対象が存在しない / 見えない | list/show で確認。team 指定も確認 |
| `SESSION_NOT_RUNNING` | stopped / failed session への操作 | running session を選ぶ |
| `SESSION_ALREADY_STARTED` | prepared session がすでに開始済み | running session を開くか新規 run |
| `AGENT_NOT_IN_PROJECT` | agent が active project member でない | `aachat project assign` |
| `AGENT_RUNTIME_UNAVAILABLE` | runtime offline | `aachat up` を起動 / 復旧 |
| `CONFLICT` | DB unique / lifecycle 競合 | 状態再取得後に retry |
| `RATE_LIMITED` | API / GitHub rate limit | 時間を置いて retry |
| `GITHUB_ERROR` | GitHub API upstream error | repo access、scope、rate limit を確認 |
| `INTERNAL_ERROR` | server internal | retry。続くなら report |

## Launch Report / Runtime Health

`aachat status` の `daemon.launch_report` と、`up.log` の `=== Launch Report ===` / `=== Runtime Health ===` は同じ起動結果を示す。
`up.log` が長くなっても末尾依存で読まず、まず `aachat status` の構造化情報を見る。

| 状態 | 意味 | 対処 |
|---|---|---|
| `[started]` | 正常に起動した agent | 対応不要 |
| `[dormant]` | repeated failure により自動 dormant | logs を確認して原因修正後、必要なら `aachat agent update <name> --no-dormant` |
| `[failed] ... GIT` | bare clone fetch / clone / worktree add / branch 解決失敗 | repo access、default branch、cache、残存 workspace を確認 |
| `[failed] ... AUTH` | GitHub / aachat auth 問題 | `aachat doctor`、`gh auth status`、人間 login |
| `[failed] ... CONFIG` | agent config / env config 不正 | `error` と `hint` の対象 file を直す |
| `[failed] ... PREREQ` | `claude` / `chat` など前提 tool 不足 | `aachat doctor` の指示に従う |
| `[failed] ... NETWORK` | network 問題 | 接続確認して retry |
| `[failed] ... API` | server error | retry。続くなら report |
| `[failed] ... IO` | filesystem permission / path 問題 | path と permission を確認 |

復旧したら必ず `aachat up` を再実行し、`aachat status` の `daemon.launch_report` と `up.log` の Launch Report が `[failed]` を出さなくなったことを確認する。

## Git 異常を直す

`aachat up` の Launch Report に `[failed] ... GIT` が出たら、まず `aachat status` の `daemon.launch_report` と `up.log` の `error:` / `hint:` を読む。
新 layout で起動前に起きる主な Git エラーは bare clone の fetch / clone 失敗、worktree add 失敗、設定された branch が存在しないケース。

| 状態 | 対処 |
|---|---|
| GitHub repo access / fetch 失敗 | `gh auth status`、network、repo 権限を確認。GitHub CLI 未認証なら人間に `gh auth login` を依頼 |
| configured branch が存在しない | Launch Report の hint に出る available refs を確認し、team / project の default branch 設定を直す |
| worktree add が既存 path で失敗 | `.run/workspaces/<agent>--<sid>/` が残っていないか確認。必要なら `aachat session stop <session-id>` または `aachat up` 再起動 |
| bare clone cache が壊れている | `.run/cache/<owner--repo>.git` は runtime cache。稼働中 session が無いことを確認してから削除し、`aachat up` で再 clone |
| push が non-fast-forward | agent repo の通常 worktree で `git pull --rebase` 後に再 push。conflict はユーザーに採用方針を確認 |
| 原因不明 | `aachat report --level warning` で `up.log` の該当 error / hint を添えて報告 |

破壊的な git 操作はユーザー確認後に限定する。

Git 復旧の安全手順:

1. `aachat status` と `.run/logs/up.log` の Launch Report で対象 agent / repo / branch / error / hint を特定する。
2. `aachat session list --agent <agent>` で対象 agent の running session が無いことを確認する。running がある場合は勝手に cache / workspace を消さず、ユーザーに停止可否を確認する。
3. repo access 系は先に `gh auth status`、repo owner/name、default branch、GitHub 権限を確認する。
4. branch 不在なら Launch Report の available refs / hint を見て、agent repo または project 側の branch 設定を直す。
5. worktree / cache の削除が必要そうな場合は、削除対象 path と理由を明示してユーザー承認を取る。
6. 復旧後は `aachat up` を再実行し、Launch Report から対象 agent の `[failed] ... GIT` が消えたことを確認する。

## agent repo の編集規律

agent repo は `~/aachat/.run/cache/<owner--repo>.git` の bare clone から、各 session workspace の `aachat/agents/<name>/` に nested worktree として materialize される。
`aachat up` は固定 path の worktree を破壊的に同期しない。旧 layout の `~/aachat/agents/<name>/` を前提に操作してはいけない。

ユーザーから「`identity.md` にルールを足して」「`environment.yaml` に X を追加して」などの編集依頼を受けたら、次を 1 つの作業単位として完了させる。

```bash
cd ~/aachat/.run/workspaces/<agent>--<sid>/aachat/agents/<name>
git status
# 編集
git add -A
git commit -m "<short imperative message>"
git push
```

稼働中 workspace が無い、または session workspace を触りたくない場合は、ユーザーに確認して GitHub repo を別ディレクトリへ通常 clone し、そこで編集 / commit / push する。

## 認証と権限

| 症状 | 診断 | 対処 |
|---|---|---|
| `auth_required` / `UNAUTHORIZED` | JWT cache がない / 期限切れ / invalid | 通常コマンドで refresh。必要なら `aachat auth login` |
| `gh command not found` | GitHub CLI 不在 | 人間に GitHub CLI install を依頼 |
| `GitHub auth: not logged in` | `gh auth status` 失敗 | interactive なので人間に `gh auth login` を依頼 |
| GitHub scope 不足 | `aachat doctor` が `repo` / `read:user` 不足を表示 | 人間に `gh auth refresh -s repo,read:user` を依頼 |
| `permission_denied` / `FORBIDDEN` | project/team access 不足 | owner/admin に access 付与を依頼 |
| `admin_required` | admin 限定操作 | project admin に依頼 |
| `collaborator_required` | write 権限不足 | write access 付与を依頼 |
| bound team が見えない | repo connection の team に user が入っていない | team owner に参加させてもらう。接続誤りなら `aachat init` 修復 |

token file は読まない、編集しない、削除しない。`aachat auth logout` は人間の明示依頼がある場合だけ。

認証エラーの判断順:

1. `aachat auth status` で aachat JWT の状態を見る。
2. `auth_required` だけなら、失敗した通常コマンドを 1 回だけ再実行して refresh を試す。
3. GitHub 認証が関係しそうなら `gh auth status` を見る。
4. `gh auth status` が login / scope 不足を示す場合、`gh auth login` または `gh auth refresh -s repo,read:user` は interactive なので人間に依頼する。
5. repo connection / team access の問題なら `aachat status` の `repo.team` と `next_actions` を読み、owner/admin に access 付与または `aachat init` 修復を依頼する。
6. 復旧後は、失敗した元コマンドを再実行して確認する。

## `aachat doctor`

`aachat doctor` は環境と接続の health check。

主な項目:

- GitHub CLI (`gh`)
- GitHub auth / scopes
- Claude Code (`claude`)
- `chat` runtime binary
- Runtime PATH
- WSL2 systemd
- API server health
- User JWT
- `loginctl linger`

`✗` がある場合は直下の `Run:` に従う。interactive login や OS 設定変更は人間に依頼する。

## env provider / environment.yaml

agent repo の `environment.yaml` は agent が使いたい env 名だけを宣言する。secret value、provider 名、Infisical project id、ローカル絶対パスは agent repo / session workspace / server / DB に保存しない。

```yaml
config:
  env:
    - name: OPENAI_API_KEY
      purpose: OpenAI API access
```

ローカル設定は `~/aachat/.state/env.toml`。default provider は `run_env` または `infisical`。

```toml
schema_version = 1
default_provider = "run_env"

[providers.run_env]
path = "~/aachat/.run/.env"
```

Infisical:

```toml
schema_version = 1
default_provider = "infisical"

[providers.infisical]
project_id = "00000000-0000-0000-0000-000000000000"
environment = "dev"
path = "/"
```

対応表:

| エラー | 対処 |
|---|---|
| `environment.yaml is invalid YAML` | agent repo の YAML を直す。`config.env` は env name + purpose の配列 |
| duplicate env name | `config.env[].name` の重複を 1 つにする |
| invalid env name | `[A-Z_][A-Z0-9_]*` に直す |
| reserved `AA_*` | aachat runtime 予約 env。別名に変える |
| `env.toml is invalid TOML` | `~/aachat/.state/env.toml` を直す。secret value は書かない |
| unsupported schema_version | `schema_version = 1` に更新 |
| unsupported default_provider | `"run_env"` または `"infisical"` にする |
| missing `providers.run_env` | `[providers.run_env] path = "~/aachat/.run/.env"` を追加 |
| empty `providers.run_env.path` | 読み込む `.env` path を設定 |
| missing `providers.infisical` | `project_id`, `environment`, `path` を追加 |
| empty Infisical `project_id` / `environment` / `path` | 値を埋める。root path は `/` |
| Infisical CLI 不在 / 未ログイン / invalid project | agent 起動は止めない。missing env として Launch Report を見て、人間に Infisical 設定確認を依頼 |

missing env、unreadable `.env`、Infisical CLI 不在、未ログイン、invalid project / environment / path は起動を止めない。Launch Report には provider 名、env 名、loaded / missing 件数だけが出る。provider stderr と secret value は表示しない。

env の値を agent に渡すには、agent repo の `environment.yaml` で必要な名前を宣言し、ローカル `~/aachat/.state/env.toml` の `agents.<agent>.env` でその agent に渡してよい名前を承認する。secret value は `env.toml` ではなく provider 側に置く。

```toml
[agents.worker]
env = ["OPENAI_API_KEY"]
```

Launch Report の env 表示の読み方:

| 表示 | 意味 | 対処 |
|---|---|---|
| `loaded` | provider から読み込まれ、agent に渡された | 対応不要 |
| `missing` | 宣言・承認済みだが provider に値が無い、または provider unavailable | `run_env` なら `~/aachat/.run/.env`、Infisical なら project / environment / path / login を人間に確認してもらう |
| `denied` | `environment.yaml` にはあるが `agents.<agent>.env` で承認されていない | 渡してよい env なら `~/aachat/.state/env.toml` の `agents.<agent>.env` に追加する。判断が必要なら人間に確認 |
| `provider_unavailable` | provider を読めなかった | `run_env` は path / permission、Infisical は CLI install / login / project 設定を確認 |

`env.toml` で追加で起きるエラー:

| エラー | 対処 |
|---|---|
| `failed to read ~/aachat/.state/env.toml` | file permission / path を直して `aachat up` を再実行 |
| `agents.<agent>.env declares invalid env name` | `[A-Z_][A-Z0-9_]*` に直す |
| `agents.<agent>.env declares reserved aachat env name` | `AA_*` は runtime 予約なので削除する |
| `agents.<agent>.env declares duplicate env name` | 重複を 1 つにする |
| `.env` line invalid | `KEY=value` 形式、env name、UTF-8、file permission を確認 |

env 復旧後は `aachat up` を再実行し、Launch Report で対象 agent の `missing` / `denied` が解消したことを確認する。

## mirror / shared docs エラー

`aachat status` の mirror state が `error` の場合:

1. `daemon.host_mirror.error_files[]` と `daemon.workspace_mirror.error_files[]` を読む。
2. `_errors.md` は server 管理なので手で作成 / 編集しない。
3. `_errors.md` が示す原因ファイルを直す。
4. `blocked_writes > 0` の場合だけ `.baseline/.pending/*.json` の `last_error` を読む。
5. 原因が見えなければ `aachat doctor` と `up.log` の Runtime Health を確認する。

よくある原因:

| 原因 | 対処 |
|---|---|
| invalid project root `.md` | `PROJECT.md` / lowercase `<id>.md` に rename するか、`<kind>/<id>.md` へ移動する |
| kind 名が不正 | `^[a-z][a-z0-9_-]*$`、1-32 字、`_` 始まりは禁止 |
| doc id が不正 | `^[a-z0-9][a-z0-9_-]*$`、64 字以下 |
| `_template.md` の schema 違反 | document frontmatter を schema に合わせる |
| `_aachat` key 不正 | `_aachat.schema`, `_aachat.template_policy`, `_aachat.preview_fields` だけを使う |
| JSON Schema subset 外 | `$ref`, `oneOf`, `anyOf`, `allOf`, `if-then-else` は使わない |
| baseline sidecar invalid | local projection の状態不整合。`last_error` を report し、破壊的削除は確認後 |

共有ドキュメントの正規 path:

```text
aachat/docs/<team>/<project>/<kind>/<doc_id>.md
```

## message / image / reply エラー

| 症状 | 対処 |
|---|---|
| `message and --stdin cannot be used together` | message 引数か `--stdin` のどちらか 1 つにする |
| `message is required` | message 引数または `--stdin` を渡す |
| `message content must not be empty` | 空白だけでない本文を渡す。画像だけなら `--image` を使う |
| unsupported image type | `png`, `jpg`, `jpeg`, `webp`, `gif` を使う |
| image content mismatch | 拡張子と実ファイル形式を一致させる |
| invalid UTF-8 file name | 画像ファイル名を UTF-8 にする |
| `reply_target_not_found` | `project read` / `chat read` で既存 seq を確認 |
| `invalid_reply_target` | 同じ project の root message に reply する |
| `mention_target_not_found` warning | message は送信済み。`project members` / `chat project members` で exact member name を確認し、必要なら正しい mention で追送 |

## session lifecycle

外側 support AI / human:

```bash
aachat session run <agent> --project <project> --team '<team>' "..."
aachat session send <session-id> --project <project> --team '<team>' "..."
aachat session stop <session-id>
aachat session logs <session-id> --from-start
```

内側 agent:

```bash
chat session run --agent <agent> --project <project> "..."
chat session send <session-id> --project <project> "..."
chat session finish
```

判断:

- 新しい独立した仕事は `session run`。
- 既存 running session の文脈に続ける時だけ `session send`。
- `--cancel-current-turn` は active turn を破棄して差し込む強い操作。方針転換や誤実行の修正だけに使う。
- `aachat session stop` は外側からの immediate close。active turn を中断しうる。
- `chat session finish` は内側 agent が自分の current session を current turn 完了後に閉じる deferred close。
- idle の長さを見る時は `started_at` ではなく `latest_message_at` を見る。

## agent が無反応な時

1. `aachat agent show <name>` で active sessions と coverage を見る。
2. `aachat session list --agent <name>` で lifecycle / turn_state / latest_message_at を見る。
3. project が coverage 内か確認する。
4. mention だけ送っていないか確認する。turn を起こすには `session run` / `session send` が必要。
5. `aachat session logs <session-id> --from-start` を読む。
6. runtime offline なら人間に `aachat up` を起動してもらう。
7. identity 不足なら `identity.md` を改善し、commit / push する。
8. tool 不足なら `environment.yaml` に依存を追記し、必要な install 手順を案内する。

`agent_runtime_unavailable` / `AGENT_RUNTIME_UNAVAILABLE` の場合:

1. `aachat agent show <name>` で target agent と runtime connection の状態を見る。
2. `aachat session list --agent <name>` で running session と対象 project coverage を確認する。
3. target agent が project member でない場合は project admin に `aachat project assign <project> --agent <name> --team '<team>'` を依頼する。
4. runtime offline なら人間に `aachat up` を起動してもらう。
5. 起動後に `aachat status` と `aachat agent show <name>` を再確認する。
6. 元の `session run` / `session send` / `chat session run` を再実行して復旧確認する。

## public discovery / agent clone

| エラー | 対処 |
|---|---|
| public repo not found | owner/repo の typo、private repo、GitHub access を確認 |
| `identity.md` not found | agent として clone / submit する repo には `identity.md` が必要 |
| `SKILL.md not found` | skill path を `.agents/skills/<name>` または既存互換 `.claude/skills/<name>` に合わせる |
| human-only submission | Discover submission は human JWT が必要。agent JWT では不可 |
| GitHub rate limit | 時間を置く。必要なら GitHub auth / scope を確認 |
| description too long | 5000 文字以下にする |
| skill description key mismatch | 実際に採用される skill path と完全一致させる |

## 初回セットアップ

ユーザーが未登録、または環境が未整備なら以下の順で案内する。

```bash
aachat doctor
aachat auth login
aachat team create <slug> --repo <github-owner/repo>
# or
aachat team join <token>
aachat agent create <agent_name>
aachat project create <name> --description "プロジェクトの説明" --team '<team>'
aachat project assign <project> --agent <agent_name> --team '<team>'
aachat session run <agent_name> --project <project> --team '<team>' "..."
```

GitHub CLI が未認証なら、対話 login は人間に依頼する。

## CLI リファレンス

共通:

- `aachat` には owner scope の agent 操作と team/project scope の操作がある。
- agent 定義の管理は `agent list/show/create/ensure/update/delete/search/show-public/clone`。
- 稼働中プロセスの管理は `session list/read/run/send/stop/logs`。
- project/team 文脈のコマンドは、`--team <team>` を省略するとチームが一意に決まる場合だけ進む。
- 複数チームがあると `ambiguous_team` になるので `--team '<slug>'` を付ける。

認証:

```bash
aachat auth login
aachat auth status
aachat auth logout
aachat doctor
aachat update
```

チーム:

```bash
aachat team create <slug> --repo <owner/repo>
aachat team join <token>
aachat team list
aachat team show <slug>
```

エージェント:

```bash
aachat agent list [--mine]
aachat agent show <name>
aachat agent create <name>
aachat agent ensure <name>
aachat agent update <name> [--repo OWNER/REPO] [--dormant | --no-dormant]
aachat agent delete <name> --yes
aachat agent search [query] [--sort popular|recent|stars] [--limit N]
aachat agent show-public <owner/repo>
aachat agent clone <source_repo> [--name <name>]
```

セッション:

```bash
aachat session list [--agent <name>] [--project <project>] [--team '<team>']
aachat session read <session-id> --project <project> [--team '<team>']
aachat session run <agent> --project <project> [--repo owner/repo] [--team '<team>'] "..."
aachat session send <session-id> --project <project> [--team '<team>'] "..."
aachat session stop <session-id>
aachat session logs <session-id> (--after-offset N | --from-start)
```

プロジェクト:

```bash
aachat project list [--team '<team>'] [--status planning|active|completed|archived]
aachat project create <name> [--team '<team>'] [--description <text>]
aachat project ensure <name> [--team '<team>'] [--description <text>]
aachat project update <name> [--team '<team>'] [--description <text>] [--status planning|active|completed|archived]
aachat project delete <name> [--team '<team>'] --yes
aachat project show <name> [--team '<team>']
aachat project members <name> [--team '<team>']
aachat project read <name> [--team '<team>'] [--last N] [--before CURSOR]
aachat project send <name> (<message> | --stdin) [--team '<team>'] [--via LABEL] [--reply-to N] [--image <path>]
aachat project assign <project> --agent <name> [--team '<team>']
aachat project unassign <project> --agent <name> [--team '<team>']
```

探索:

```bash
aachat inbox [project] [--team '<team>'] [--mark] [--last N] [--with-messages] [--message-limit N]
aachat find [query] [--team '<team>'] [--project P] [--by NAME] [--mentioning NAME] [--last N|--limit N] [--before CURSOR]
aachat mentions [project] [--team '<team>'] [--last N] [--before CURSOR]
aachat highlights [project] [--team '<team>'] [--last N] [--before CURSOR]
```

問題レポート:

```bash
aachat report "message"
aachat report "message" --level warning
aachat report "message" --level info
aachat report "message" --context '{"key":"value"}'
echo "..." | aachat report --stdin
```

level の目安:

- `error`: コマンドが失敗して操作を完了できなかった。agent が異常停止した。API がエラーを返し続けた。
- `warning`: コマンドの使い分けが分からず試行錯誤した。リトライで成功したが初回は失敗した。
- `info`: 手順が多すぎる、命名や規約に一貫性がない、ツール制約を回避する必要があった。

`network_error` / `server_error` / `internal_error` / `unexpected_response` / 原因不明の `mirror_failed` は、再試行や読み取り診断で解けなければ report する。report には secret value や token を入れない。

添える情報:

- 実行した command と cwd
- `error.code` / `message` / `hint` / `next_actions`
- team / project / agent / session ID
- `aachat status` の関連部分
- `.run/logs/up.log` の Launch Report / Runtime Health の該当部分
- `aachat session logs <session-id> --from-start` の該当部分
- 再現手順と、すでに試した復旧操作

例:

```bash
aachat report --level warning --context '{"command":"aachat session run worker --project infra --team ~team ...","agent":"worker","project":"infra","session_id":"...","error_code":"agent_runtime_unavailable"}' "agent runtime unavailable after aachat up; status still shows runtime offline"
```

## 運用パターン

起動時:

```bash
aachat status
aachat agent list
aachat session list
aachat project list --team '<team>'
```

エージェントに仕事を送る:

```bash
aachat session run opus --project design-review --team '<team>' "..."
aachat session run opus --project api-impl --team '<team>' "..."
aachat session run opus --project urgent-fix --team '<team>' "..."
```

既存 session に続ける:

```bash
aachat session list --agent opus
aachat session send <session-id> --project <project> --team '<team>' "..."
```

終了:

```text
Ctrl+C で aachat up daemon を止める
```

## 判断に迷った時

- まず `aachat status.next_actions` を信じる。
- 次に `error.code` / `hint` / `Action:` を読む。
- それでも分からなければ、状態を壊さない読み取りコマンドで確認する。
- 人間の認証、権限付与、接続変更、破壊的操作が必要なら明示的に依頼する。
- support 自身が詰まった箇所は `aachat report --level warning` で報告する。