---
title: "トラブルシューティング — 症状から切り分ける"
description: "agentが文脈を踏まえない、変更が効かない、sessionが起動しない、認証・起動・同期・cloneの失敗。症状ごとに確認の順序と対処を示す。"
---

# トラブルシューティング — 症状から切り分ける

症状ごとに、確認する順序と対処を示す。ユーザーから不調の報告を受けたら、該当する症状の確認手順を上から順にたどる。どの症状にも当てはまらない場合はページ末尾の `aachat support` に進む。


## 症状から復旧手順を選ぶ

| 症状 | 次に読むものと操作 |
|---|---|
| WorkflowのStep失敗・Runのattention | retry/cancel前にRunのavailable actionsと失敗Attemptを読む：[Workflows](/ja/docs/workflows) |
| Triggerが起動しない・pause・競合 | 起動履歴と現在のstate versionを確認する。成否不明は再送前に照合する：[Triggers](/ja/docs/triggers) |
| DBがない・migrationの親が古い・SQL結果が大きい | schema/errorsを読み、受付済み書込を照合し、列数やpage sizeを減らす：[Database](/ja/docs/database) |
| Desktopの起動・更新が止まった | appとCLIの版を分けて確認し、表示された復旧手順へ進む：[Desktop](/ja/docs/desktop) |
| share期限切れ・URL紛失・受け手が開けない | scope・期限・取消を確認する。Media URLだけではpublic共有にならない：[Sharing](/ja/docs/sharing) |
| 小さいMediaでも拒否される | bytesだけでなく寸法・ページ数・長さ・形式を確認する：[容量・実行条件](/ja/docs/limits)、[Media](/ja/docs/media) |
| Agentは停止したが変更が見当たらない | repository HEAD・native提出・receipt・local observationを比較する：[コードの提出](/ja/docs/code-delivery) |
| Runtime configが拒否された | 現在のprofileと型付きoptionを読み直し、再送前に受付を確認する：[Agents](/ja/docs/agents) |
| Skill Ledgerのsourceや最近の履歴がない | ReloadとAgentの投影sourceを確認する。inventoryの容量調整でcached sourceが省略されることがあり、最近のfeedback/changeは全履歴ではない。欠測や空のrecent一覧は削除・未使用の証明ではない：[Skills](/ja/docs/skills) |


## Sessionで既存Mediaを取得できない

まず`chat --version`と`chat media --help`でdownload対応を確認します。未対応なら止め、対応版を確認してください。`media_unavailable`なら同Projectのready一覧と対象・準備状況を確認します。`media_download_failed`なら`reason`を読んで一度再試行し、再失敗を`chat report`へ報告します。成功JSONなしに内容を推測したり、残っている同名ファイルを今回の取得成功としたりしません。APIの認証・権限エラーも取得失敗と分けて確認します。[Mediaの前提・取得・読取手順](/ja/docs/media)に従い、canonical参照を保持して取得コピーを再公開しません。

## まず診断コマンド

2つの診断コマンドが切り分けの入口になる。

- `aachat doctor` — 環境・認証の診断。問題のある項目を `✗` と対処指示付きで表示する
- `aachat status` — serverへの接続と `aachat up`（daemon）の状態。Launch Report（`daemon.launch_report`）とdocument mirrorの状態を含む

## 失敗した操作の診断をsupportへ渡す

失敗した操作の時刻（timezone付き）、Team/Project、対象のSession・Run・invocationなど既存のID、使ったCLIまたはappの版、期待した結果と実際の結果を控えます。Session内の`chat`が失敗したら、stdoutだけでなくstderrのJSONと終了statusを読み、`error`と表示された`hint`・`commands`から該当する復旧手順へ進みます（[CLIの出力stream](/ja/docs/cli)）。help/versionはtextです。結果が不明な書込や起動は、既存の受付・対象状態を確認してから操作別の再送手順に従います。診断を増やす目的で同じ操作を重ねないでください。

対応版の`chat`では失敗JSONの`diagnostic`が入口です。WebのAPI失敗は、利用できる場合にbrowserのNetworkで該当requestのHTTP statusと`X-Aachat-Request-Id`応答headerを確認します。画面に出ない診断fieldが取得できるとは限りません。秘密のtoken、cookie、request bodyを含むログ全体をそのまま共有せず、必要な証拠を選びます。

| 実際に取得できた情報 | 意味と扱い |
|---|---|
| `diagnostic_id` | 診断記録を探す手掛かりです。Session ID、idempotency key、completion receiptではありません。 |
| `context.http_request_id` / `context.server_http_request_id` | clientのHTTP試行と、取得できたserver応答の相関IDです。新しいHTTP試行では新IDになり、server側は欠測や別IDの場合があります。Webでは同じserver IDを別fieldに重複表示しない場合もあります。取得元と実際の値を保持します。 |
| `context.build_sha` / `missing` | `unknown`・`dirty`や`build_unverified`なら実行buildの対応は未確認です。`server_correlation_unconfirmed`などの欠測理由も残します。`missing`はcontext内または診断直下に出る場合があり、省略されたfieldを成功・障害なしと補完しません。 |
| `context.code_location` | `failure_site`は失敗箇所、`operation_boundary`は操作の境界、`capture_only`は記録箇所を示します。示された場所だけで根本原因を断定しません。 |

`chat --version`や`aachat --version`を記録し、fieldが出ない場合は取得できなかったことを伝えます。CLIの版だけでAPI・Web・常駐runtimeも同じ版とは判断しません。診断IDがあっても配送、仕事の成功、復旧、Sentry受信の証明にはなりません。

[Sessionログの手順](/ja/docs/cli)で読むstderrと、常駐runtimeの診断logは別です。server側の既存stdoutや設定されたruntime logが必要なら、権限のある管理者/supportへ上記の時刻・IDを渡して照合を依頼します。閲覧不能は空ログではなく未確認であり、全ログの保存や保持期間を保証しません。HTTP相関とredirectで止まった場合は[Developer API](/ja/docs/developer-api)を参照します。修復後は元の操作の結果を別に確認してください。

## New ProjectのCreateが無効、またはLeadが見つからない

Nameだけでは作成できない。**Name・Lead・Brief**を確認する。Nameは小文字英数字とハイフンの2〜30文字で、`stream`・`dm`・`repo`は予約名。任意のdescriptionではBriefを代用できない。

Lead候補がなければ対象teamと所有agentを確認する。New Projectまたは人間向けCLIでは、対象teamのactiveな人間member、または自分が所有するagentを選ぶ。子Projectなら親がactiveで、自分が親のAdminまたはcurrent Leadである必要がある。選択したLeadは必要に応じて作成時に親へ追加されるため、親への事前参加は不要である。Session agentの`chat project create`では、current parent Lead Sessionから親のactive memberを選ぶ。最初の親なしProjectの手順は[セットアップ](/ja/docs/setup)、詳細条件は[Projects](/ja/docs/projects)を参照する。

受付後に応答がない、または通信エラーで作成できたか不明なら、先にProjectsで作成済みか確認する。agent Leadなら受付されたSessionを確認し、同じセットアップ依頼を重ねる前に、以下のSession起動・runtime認証の確認へ進む。人間Leadなら通知とProject・Briefを確認して人間として仕事を始める。この結果でagentの応答は始まらない。

## Askへ回答したが続かない

回答を保存できたかと、Sessionが継続したかを分けて確認する。

1. **Answered**に回答があるか、revisionと**Change history**を確認する。選択肢を選んだだけならdraftなので**Save answer / Save only**で保存する。エラーや競合があれば最新回答とdraftを比較して解消する。回答できるのは担当者またはProject Adminである。
2. source Sessionを開く。対応したWeb/API版では**Awaiting results**からcomposer上の待機パネルを確認できる。対象を展開し、リンクから未確定の別Ask・Session・Runを確認する。**Couldn't load wait details.**ならパネルの**Retry**で再読込する。これは配送の再試行ではない。パネルがない、または読めない場合はtranscriptの登録受付とwait IDを調べる。Session agentは`chat wait show <wait-id> --project <team>/<project>`で読める（[CLI](/ja/docs/cli)）。パネルがないだけで未登録としない。
3. 全対象が確定しても継続受付は次の30秒周期の確認処理まで遅れ得る。その間にpolling、再登録、手動送信を重ねない。**Wait completed**があれば展開して各結果を確認する。その周期後も通知がなければ、source Sessionが`stopping`・archivedか、そのagentにProjectのcollaborator権限が残っているかを確認する。**Needs attention**は失敗・要確認・取消の対象があるという意味で、回答保存の失敗ではない。対象リンクで成果を読み、Sessionがfailedなら下のruntime復旧へ進む。
4. 通知配送を別に確認する。**Delivery pending**は配送待ちなので、仕事を追加する前にsource Sessionの状態を見る。**Delivery failed**では同じ通知を展開し、エラーを読み、その原因を解消してから、利用可能なら**Retry delivery**を使う。Sessionが`running`で、workspaceの操作が可能であり、接続済みで再接続中でないことが必要である。`Retry requires a running Session.`ならSessionの復旧へ進み、waitを再登録しない。**Delivery cancelled**は配送済みではなく、failed用の再配送操作は出ない。通常Sessionの仕事では、sourceを復旧または置き換えた後、保存済み結果のリンクかIDを含む新しいfollow-upを一度送る。Resumeだけでは取消済み通知は再キューされない。Workflow Stepなら下の復旧経路を使う。Retry deliveryは新規Session起動、Workflow Step再実行、保存済み結果snapshotの変更を行わない。
5. 配送が進んだら、次のturnと保存済み回答を使った成果を読む。system通知の保存、Retry受付、Resume受付だけで成果が出たと判断しない。system通知は通常キューの編集・削除・**Run now**の対象ではない。
6. wait未登録の通常Project Askは保存だけで新しいturnを起動しない。継続が必要な同じ仕事のsourceがrunningなら、保存済み回答を手動follow-upで一度送る。停止済みなら下の復旧手順へ進む。登録不明のまま両方を試さない。

対応するAPI・DB・Webの提供後、**Answer saved. The session will continue when all wait conditions are met.** は保存済みで条件待ち、**Chat continuation accepted** は自動継続受付済みを示す。後者でもagentの読了や成果成功は未確認なので、source Sessionの次turnと成果を読む。表示がなくても未登録とは断定しない。混在する回答の **Send N answers to session** は自動対象を除いた件数であり、件数が少ないだけで保存失敗と考えて再送しない。受付後に回答を変更した場合は **Change history** のrevision、現在の表示、元Sessionの状態を確認する。変更後の回答が必ず自動送信されるとは限らない（[回答保存と継続](/ja/docs/projects)）。

取消はsettledでも承認ではなく、後の回答変更も同じwaitを再発火しない。通知の意味と対応版の条件は[Sessions](/ja/docs/sessions)、回答条件は[Projects](/ja/docs/projects)を参照する。解決しなければProject・Session・Ask・wait ID、回答revision、取得できるcontinuation・delivery ID、状態、エラーと時刻を揃えて調査へ渡す。

## REPORT不足でDoneにできない

`project_report_required_for_completion`または“Create or update Current report, then retry completion.”は、Leadを持つactive ProjectのREPORTが不足しているという意味である。

current Leadに、正確な`aachat/projects/<team>/<project>/docs/REPORT.md`へ成果・確認した根拠・残る差を保存するよう依頼する。**Docs**で同期済みの本文を確認し、成果を受け入れてからAdminがDoneを再試行する。空文書、別名の`report.md`、planningへの変更で条件を回避しない。メニュー自体がなければProject Adminへ操作を依頼する。

保存済みなのに同じ拒否が続く場合は、下の「Shared Documentsが同期されない」を確認し、Project ID・REPORTのpathと保存版（取得できればrow_version）・エラーcode・時刻を残す。文書の責任は[Shared Documents](/ja/docs/shared-documents)、受け入れは[Projects](/ja/docs/projects)を参照する。

## agentがprojectの文脈を踏まえていない

応答が、projectのこれまでの決定・成果を無視しているように見える症状。

agentがsession開始時に読む文脈の経路を順に確認する。どこが欠けているかで対処が変わる。

1. **projectのPROJECT.md** — 安定したPurpose、Outcome、Outputs、判断原則・境界、curated Context Map、Approachが書かれているか。無い、またはこの安定契約が古い場合は整備する。進捗・担当・handoff・ログ・未解決メモで更新しない
2. **Context Mapとgenerated `index.md`** — `PROJECT.md`の厳選リンクから必要な正本へ進めるか。そこに無いdocumentは、全件を列挙するgenerated `index.md`から探す
3. **直前の動的文脈** — 前のsessionのtranscript、短いproject message、または通常のShared Documentにhandoffがあるか。handoffを`PROJECT.md`へ移さない（[Shared Documents](/ja/docs/shared-documents)）
4. **agent repoのmemory** — project横断で持ち回るべき経験則・知識がagent repoの `memory/` にあるか。無ければ書いてpushする。反映は次のsessionからである

agentが読む文脈の2層構造（agent自身の記憶 / 仕事の文脈）の定義は [基本概念](/ja/docs/concepts) を参照する。

## identity / skills / memoryの変更が効いていない

agent repoを編集したのに、agentの振る舞いが変わらない症状。

原因は反映のタイミングである。agent repoの変更は、**commitしてpushした後の次のsessionから**反映される。稼働中のsessionには反映されない。

対処: 変更をpushし、新しいsessionを起動する。agent repoの構造は [Agents](/ja/docs/agents) を参照する。

## sessionが起動しない

`session run` やtarget chipへの依頼でsessionが始まらない症状。次の3条件を順に確認する。

1. **projectのstatusが `active` か。** sessionを実行できるのはactiveなprojectだけである。WebUIのprojectヘッダーのstatus表示で確認する
2. **agentがそのprojectのmemberか。** `session run` のagentはproject memberとして解決される。memberでなければprojectに追加する
3. **agentのowner側で `aachat up` が稼働しているか。** agentのruntimeはownerのマシンで動く。onlineかどうかはWebUIのagent表示または `aachat agent list` で確認する。`dormant` 表示のagentは `aachat up` の起動対象から外れているため、`aachat agent update <name> --no-dormant` で復帰させる

## sessionが止まって見える

sessionは起動したが応答が進まない症状。

- **Permission待ちを確認する。** agentは影響の大きい操作の前に実行許可を待ち、応答があるまで待機し続ける。WebUIのworkspaceパネルに許可ダイアログが出ていないか確認し、許可または拒否を選ぶ
- **@mentionだけで送っていないか確認する。** 正確な `@<agent>.<owner>` は通知であり、sessionの実行トリガーではない。target chipで宛先に指定するか、`session run` を使う（[Sessions](/ja/docs/sessions)）

## sessionが途中で止まった・停止した — 何が残るか

sessionが異常終了（`failed`）したり途中で停止しても、それまでの仕事は消えない。

- **会話の記録は残る。** session recordとtranscriptはserverに保存されており、`aachat session read` でいつでも確認できる
- **projectに残した分は次の入力になる。** そのsessionがShared Documents・Timelineに残した成果物と判断は、次のsession（同じagentでも別のagentでも）がそのまま読んで続きから進められる

途中状態を確認し、同じ仕事が再開可能ならagentの明示的な`chat session send <session-id> --project <project> --resume "追加指示"`を使う。`<session-id>`と`<project>`を対象Session・Projectの値に置き換え、追加指示の本文を指定する。復元できない場合や別の仕事は新しいSessionへ必要な成果を引き継ぐ。条件は[Sessions](/ja/docs/sessions)を参照する。

runtimeのprompt実行エラーでSessionが`failed`になる場合がある。wait通知の配送失敗とは別である。まず保存済みtranscriptと、ownerのマシンで`aachat session logs <session-id> --from-start`を確認する。報告されたruntimeの原因を解消した後、SessionのResume適格性と拒否理由を見る。同じ仕事を続ける適格な`stopped`・`failed` Sessionでは、Session ownerがWebUIの**Resume**を使える。eligibleなrunning agentは上のAgentコマンドを使える。ownerでないProject Admin・collaboratorは、そのいずれかへ復旧を依頼する。その後、runtimeの再接続と次の成果を確認する。`starting`・`stopping`の間は待ち、Resumeを重ねない。archivedやworkspace・設定・Project coverageを復元できないSessionはこの経路を使えない。

**Workflow Step**ならRunを開き、`available_actions.retry_steps`に示されたStepだけWorkflow retryを使う。Published Workflow Stepの失敗はchild Runを開いて失敗した内部Stepをretryする。新しいAttemptを作る操作であり、汎用のSession Resumeは使えない。新Attemptと出力を確認してから復旧を判断する（[CLI](/ja/docs/cli)）。

### runtime再起動後に同じ仕事を送る前に

1. 元Sessionを開き、受付turnと保存済みtranscriptを読みます。`starting`なら回復中の可能性があるため、run/sendを重ねず次の状態・応答を確認します。
2. 成果文書、working tree、push・PR等のdeliveryと外部操作の結果を確認し、既に実行された仕事を切り分けます。受付済みの仕事は条件付きで再配送されるため、外部操作が一度だけとは限りません（[回復条件](/ja/docs/sessions)）。
3. 回復が止まったら、元Session/Run ID、受付turn、時刻、Project状態、エラーcode/body、API/runtimeの利用版、既存成果を揃えて管理者へ伝えます。403等の拒否は対象Projectと権限を確認し、状態を読み直すまで操作を繰り返しません。復元できる一般Sessionだけ上のResume手順へ、Workflowの終端AttemptはRunで提示されたretryまたは新Runの条件へ進みます。

検索結果が空でも仕事の消失とは限りません。findから除外されるTrigger/Externalの起動指示は元Sessionのtranscriptで確認します。`read --match`の成功した空応答は指定Project・窓の不一致だけを示し、403・404・timeoutは読取失敗です。[検索範囲と抜粋の限界](/ja/docs/sessions)を確認してください。

Tool出力が履歴にない場合は、利用版と[Sessionの保存境界](/ja/docs/sessions)を確認してください。新しい永久履歴にはTool出力を保存しません。出力の欠測、Toolが実際に返した空の結果、履歴の読取失敗は別であり、欠測だけでは実行の成功・失敗を判断できません。保存済みの状態・最終応答とShared Documents等の実成果を照合し、欠測を埋めるためだけに書込や実行を繰り返さないでください。相談が必要なら、対象Session ID・時刻・利用版・実際に得た診断と未取得の情報を、上記の相談手順に沿って伝えます。

## ログを見たい

知りたい内容によって、使うコマンドと見る場所が異なる。

| 知りたいこと | コマンド | 保存場所 |
|---|---|---|
| 会話の内容・応答（transcript） | `aachat session read <session-id> --project <project>` | server |
| 実行エラー・runtimeのstderr | `aachat session logs <session-id> --from-start` | ローカル（`~/aachat/.run/logs/`） |

session IDは `aachat session list --agent <name>` で調べる。

## 認証で失敗する

CLIが認証エラーを返す症状。まず状態を確認する。

```bash
aachat auth status
aachat doctor
```

`aachat doctor` でよく出る `✗` は次の2つで、対処は `✗` 行に添えられた指示に従う。

- `✗ User JWT: expired` — aachatのサインインが期限切れ。`aachat auth login` はローカルの `gh` トークンから短命JWTを発行するため、`gh` が認証済みなら非対話で完了する
- `✗ GitHub auth: not logged in` — GitHub CLIが未認証。`gh auth login` または `gh auth refresh -s repo,read:user` は人間が手で実行する必要がある

## `aachat up` が起動失敗する・途中で落ちる

起動結果はLaunch Reportに記録される。

```bash
aachat status                    # daemon.launch_report を見る
cat ~/aachat/.run/logs/up.log    # === Launch Report === のセクション
```

`[failed]` の行には `action:` が付いており、その指示に従う。カテゴリ別の目安は次のとおり。

| カテゴリ | 見る場所 |
|---|---|
| `[failed] ... GIT` | GitHubへの接続・認証・ブランチ設定 |
| `[failed] ... AUTH` | `gh auth status` |
| `[failed] ... PREREQ` | `aachat doctor` の指示 |

workspace cleanupとruntime readinessは別の状態として読む。

- `[started]`と`workspace_warning`が同居する場合、runtimeはreadyである。過去workspaceを保守のため保存しているので、`aachat doctor`で全pathと修復手順を確認する
- authoritative session snapshot取得またはorphan reconciliationに失敗した場合、resumable workspaceを保護できると証明できないため、そのagentだけをofflineに保つ。API接続を直して`aachat up`を再実行し、起動を通すためにworkspaceを削除しない
- 新しいsessionが保存済みworkspaceと衝突した場合、そのsessionだけが失敗する。session errorと`aachat doctor`を確認し、local workを保存してから、報告されたworkspaceだけを修復または削除する

`aachat status`はmaintenance件数を`daemon.launch_report.workspace_maintenance`に返し、readiness blockerにせず`session_workspace_maintenance` warningとして案内する。

Fresh SessionまたはWorkflow Sessionが`workspace_capacity_insufficient`で失敗した場合、runtimeはtoolやworkspace materializationを開始していない。`aachat status`の`workspace_capacity`でcurrent free/required/known cache/retained bytesを確認し、`aachat doctor`に出るartifact path・disposition・reasonを読む。保持されたdirty sourceやlocal-only commitを先にcommit/pushまたは別のdurable surfaceへ保存し、doctorが示す一つのactionに従ってから新しいSessionを開始する。Resume/FreshRetryの強制再実行やENOSPC後のtool retryで回避しない。

## 環境変数がagentに渡らない

APIキーなどが届かず、agentが「キーがない」と報告する症状。

Launch Reportのagentごとのenv行を確認する。

```bash
cat ~/aachat/.run/logs/up.log    # env: provider=... loaded=N missing=N denied=N の行
```

- `env_loaded` — 実際に渡された変数
- `env_missing` — `environment.yaml` で宣言されているが、値が見つからなかった変数
- `env_denied` — 値はあるが、渡すことが承認されていない変数（deny-by-default）
- `provider_unavailable` — provider自体が読めていない。`.env` のパス・権限、またはInfisicalのCLI・ログイン・`env.toml` の設定を確認する

`missing` / `denied` に出ている変数名を手がかりに設定を直し、`aachat up` を再起動する。secretの扱いの全体は [Environment](/ja/docs/environment) を参照する。

## Shared Documentsが同期されない

agentが作ったはずのdocumentが見えない、編集が反映されない症状。

```bash
aachat status
```

`daemon.host_mirror.state` または `daemon.workspace_mirror.state` が `error` の場合、`error_files[]` に原因ファイルが列挙される。自動生成される `_errors.md` は編集せず、そこに書かれた原因ファイル側を直す。直しても回復しなければ `aachat up` を再起動する。

前提として、Shared Documentsの正本はserverであり、ローカルの `aachat/projects/` はprojectionである。同期は `aachat up` 稼働中のみ行われる（[信頼境界](/ja/docs/trust-boundary)）。

## Discoverのcloneが失敗する

clone実行時に次のようなエラーが出る症状。

```
Could not access repository '<owner/repo>'.
  Check that the repository exists and is public (or you have access).
```

1. 元agentのrepoがprivateになっていないか。privateなら、公開されている別のagentを選ぶか、作者にアクセス権をもらう
2. GitHubのAPIレート制限に達していないか（`gh api rate_limit`）。達していれば時間をおいて再実行する
3. scope（`repo`, `read:user`）が揃っているか（`aachat doctor`）。不足していれば `gh auth refresh -s repo,read:user` を実行する

## skill投影またはprecedenceが期待と違う

Launch Reportにはworkspace / Platform collision、missing `SKILL.md`、symlink / special file / non-UTF8 pathが出ることがある。同名でもsetupを失敗させず、意図的にshadowする場合がある。

1. Team / Agent skillを`.agents/skills/<name>/SKILL.md`または`.claude/skills/<name>/SKILL.md`の通常fileにする。repo直下の`skills/`は使わない
2. workspace / Team skillが`aachat-session`等のPlatform skillと衝突している場合はworkspace側をrenameする。このcollisionはsetup errorになる
3. Agent skillがPlatform名と同名の場合、setupは成功するがPlatform版がshadowする。custom版を使いたいならAgent skillをrenameする
4. workspace / TeamとAgentに同じ非Platform名のskillがある場合、workspace側が意図的にshadowする。意図しないならどちらかをrenameする
5. symlink、directoryだけのskill、特殊file、不正なfile名を通常のUTF-8 fileへ置き換え、commit / pushして新しいsessionを起動する

正本とprecedenceは[Skills — 能力の正本と改善履歴](/ja/docs/skills)。

## Claude workspace設定でprepareが失敗する

Claude runtimeはworkspace repoのhooks / MCP / plugins / commands / custom allow-deny設定を保持し、aachatに必要なpermissionをmergeする。git管理されたsettingsをaachatが直接書き換えることはない。

repoの明示denyがaachatの必須permissionと衝突した場合は、silentに迂回せずprepareを失敗させる。Launch Reportの対象permissionを確認し、repo側policyを意図的に変更するか、その作業に合うruntime / repoを選んで新しいsessionを起動する。

CodexでShared Document write直後のvalidation feedbackが見えない場合は既知制限である。`aachat doc check <path>`を実行するか、inline hook feedbackが必要ならClaude runtimeを使う。

## External Session Runが拒否・重複・起動失敗する

まずHTTP statusとresponseの`status` / `session_id` / `web_url`を確認する。

1. 401 / 403ならtokenの入力、expiry、Rotate / Revokeの有無を確認し、漏洩が疑われるtokenは再利用せずRotateする
2. membership系の拒否ならprojectがactiveか、credential作成者と対象agentが現在も必要なproject roleを持つか、agent ownerが変わっていないかを確認する
3. idempotency conflictなら、同じkeyにtext / metadata / execution contextの異なるrequestを送っていないか確認する。同じ仕事のretryは同じrequestのまま、新しい仕事だけ新しいkeyにする
4. accepted後の起動失敗は返されたsessionとowner側のLaunch Reportを確認し、runtimeを復旧してから既存invocationの状態を確認してretryする

credentialとrequestの正本は[External Session Runs](/ja/docs/external-session-runs)。

## Project HTMLを更新したのに表示が古い

source sync後のserving snapshot rebuildが失敗すると、以前の正常snapshotが表示され続ける。HTML catalogのrebuild statusとerrorを確認し、原因fileを直してrebuildする。`aachat up`のsync状態だけを見て「表示更新済み」と判断しない（[HTML](/ja/docs/html)）。

## Archiveを受け付けられない・完了しない

**確認前に止まる場合：** Project Adminであることと、対象がplanning / active / completedであることを確認する。確認画面のactiveな子Projectは、成果確認後にDoneにするか、親を付け替えるか、影響を確認してArchiveする。他Projectも扱うWorkflow Sessionが示されたら、その仕事を終えてから確認を読み直す。確認内容が変わったというエラーは、画面を開き直して最新の件数・対象を確認する。ヘッダーのArchived選択などで「Archive confirmation required」が出た場合は、SettingsのArchiveから確認を開く。

**親の付け替えで止まる場合：** `project_reparent_status_conflict` は、付け替える子がplanning / activeでない、または新親がactiveでない場合のエラーである。子は必要に応じて復帰し、新親はactiveなProjectを選ぶ。旧親と新親のAdmin権限も必要で、循環する親子関係にはできない。これとは別に、子または新親がArchive処理中なら `Archive is in progress.` で拒否される。statusの条件だけを直しても処理中の制約は解除されない。Archiveの収束を確認してから状態と付け替え先を再確認する。

**受付後に進まない場合：** Projectを開き直し、**Archive in progress**のRemaining RunsとSessions waiting to stopを見る。通常Sessionが動いているだけではArchive失敗とはいえない。**Could not complete Archive**が出たらエラー本文と示されたRun / Sessionを開き、問題を確認したうえでAdminが同じProjectの **Retry** を選ぶ。Retryの受付も完了ではないため、Archivedになったことを確認する。進捗を読み込めない場合は完了と判断せず、読み込みをやり直す。

status変更・削除・親の付け替えで処理中のArchiveを迂回しない。解消しない場合は、Team / Project、発生時刻、status、残Run数・停止待ちSession数、エラーcode / messageと示されたID、利用版を添えて管理者へ伝える。認証情報は含めない。復帰後も取消済みの仕事は自動復活しない（[Projects](/ja/docs/projects)）。

## project削除が失敗した

project deleteは非同期operationで、WebUIにDeleting / Deletion failed / Retryが表示される。Deletion failedならerrorを確認し、同じprojectのRetryから再開する。新しい同名projectを作って回避せず、元operationを収束させる。削除前に戻したい場合はdeleteではなくarchiveを使う（[Projects](/ja/docs/projects)）。

## それでも解決しないとき

対話型サポートを起動する。

```bash
aachat support
```

症状をそのまま伝えると、ログの調査から修復までを対話的に進められる。

## 関連ページ

- sessionの仕様（状態遷移・記録・workspace・委任）は [Sessions](/ja/docs/sessions)
- agent repoの構造と反映タイミングは [Agents](/ja/docs/agents)
- secret・環境変数の仕組みは [Environment](/ja/docs/environment)
- skill collisionは [Skills — 能力の正本と改善履歴](/ja/docs/skills)
- 用語の定義は [用語集](/ja/docs/glossary)