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

問題が起きたら aachat support を起動してください。診断・修復・確認を案内します。ターミナルと選択したCLIが必要です。既定はClaude Codeで、Codexは aachat support --provider codex で選択できます。症状やSession ID・失敗codeは起動後に伝え、秘密情報はコマンド引数に入れないでください。

aachat support

以下はsupport agentが確認する内容です。利用者がdoctor・status・手動復旧を選んでから始める必要はありません。agentは同梱された初期診断を使い、症状に必要な範囲を調べ、修復後に元の操作を確認します。停止・破壊的な清掃・報告送信はsupport契約の承認条件に従います。

エラーcodeが手元にあるときはエラーコード索引から引ける。

成否がわからない操作（通信が切れた、応答が返らなかった）は、同じ操作を重ねる前に、最初の操作が受け付けられたかを確認する。これはこのページ全体に共通する原則である。

症状から探す

まず診断する

support agentは必要に応じて次の診断APIを使う。起動時に初期doctor結果を渡すため、機械的に再収集しない。どちらもstdoutに共通のJSONを返す。

• aachat doctor — 環境・認証・同期・workspaceの期限付き読取専用診断。data.diagnostics.overallはhealthy・issues_found・incomplete・attention_needed。issues[]のcategory・code・target・reasonを読み、next_actionsで対処、recheckで再確認する。任意検査のunknownもincompleteとなる。healthyは検査範囲で指摘なしという意味で、providerや現在の同期成功を保証しない。全項目はaachat doctor --view checks（data.diagnostics.checks[]）で読む
• aachat status — 現在の要約。dataはconnection（repo接続とTeam）、auth、daemon（stateがrunning・stopped・unknown、log_path）、projection（同期のstate・reason・last_sync_at）と、観測できなかった項目のgaps[]を返す。容量不足やworkspace保守はwarnings[]、次に行う操作はnext_actionsに出る。起動結果（Launch Report）は含まれないので、up.logで読む（下記）

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

失敗した操作の時刻（timezone付き）、Team/Project、対象のSession・Run・Askなど既存のID、使ったCLIまたはappの版、期待した結果と実際の結果を控える。

Session内のchatは、成功も失敗もstdoutに1つのJSONを返す。成功は{"ok":true,"data":{...}}、失敗は{"ok":false,"error":{"code","message",...},"data"?}である。終了コードは0が成功、1が実行の失敗、2が入力・引数の誤りである。error.codeと、あればhint・commandsを読み、該当する復旧手順へ進む。--helpと--versionはtextを返す。

失敗JSONのerrorはcode・messageと、あればproject・field・candidates・commands・hintを持つ。診断ID（diagnostic）のfieldは含まれない。supportへはerror.codeとmessageをそのまま渡す。WebのAPI失敗は、browserのNetworkで該当requestのHTTP statusとX-Aachat-Request-Id応答headerを確認する。秘密のtoken、cookie、request bodyを含むログ全体をそのまま共有せず、必要な証拠を選ぶ。

chat --versionやaachat --versionを記録する。CLIの版だけでAPI・Web・常駐runtimeも同じ版とは判断しない。

server側のlogが必要なら、権限のある管理者/supportへ上記の時刻・IDを渡して照合を依頼する。閲覧できないことは空ログではなく未確認である。修復後は元の操作の結果を別に確認する。

起動・認証・環境

aachat up が起動失敗する・途中で止まる

起動結果はLaunch Reportとしてup.logに記録される。aachat statusはLaunch Reportを返さない。

aachat status                    # daemon.state・daemon.log_path・warnings・next_actions を見る
aachat launcher status           # 常駐runtimeの状態（何も起動しない）
cat ~/aachat/.run/logs/up.log    # === Launch Report === と === Runtime Health === のセクション

up.logはaachat upのdaemonが動き始めてから書かれ、起動のたびと10 MiBごとにup.log.1〜up.log.8へ回転する（最大9ファイル）。実際のpathはaachat statusのdaemon.log_pathで確認する。同じ失敗が続く場合、terminalには60秒ごとにまとめて表示され、詳細はこのlogにある。Sessionごとのagentのstderrは~/aachat/.run/logs/<agent>/<session-id>-agent-stderr.logに分かれている。

Launch Reportの[failed] <agent>の下にはError [<カテゴリ>]: ...とaction:の手順が並ぶ。まずaction:に従う。カテゴリ別の目安は次のとおり。

Agent repoやSession workspaceを準備するGitのls-remote・fetchは、接続切断・一時的な名前解決失敗・HTTP 5xxに限り最大4回試す（待機は約1・2・4秒）。認証・権限・存在しないrepoやref・ローカルの破損は再試行しない。GITの失敗が出たら、この自動再試行の後の結果である。原因を直してからaachat upを再実行する。

workspaceの保守とruntimeの準備は別の状態として読む。

• [started]とworkspace保守の警告が同居する場合、runtimeはreadyである。過去のworkspaceを保守のため保存しているので、aachat doctorで観測できた対象と次の行動を確認する。期限超過なら全pathは未確認であり、保守警告をすべて消すことは起動条件ではない。aachat statusではwarnings[]のsession_workspace_maintenanceに件数と対象agentが出る
• 生存Sessionの一覧取得に失敗した場合、再開できるworkspaceを守れると確認できないため、そのagentだけをofflineに保つ。API接続を直してaachat upを再実行する。起動を通すためにworkspaceを削除しない
• 新しいSessionが保存済みworkspaceと衝突した場合、そのSessionだけが失敗する。Sessionのエラーとaachat doctorを確認し、local workを保存してから、報告されたworkspaceだけを修復または削除する

sync protocolの不一致で止まった場合： aachat statusのprojection.stateがerrorになり、projection.reasonに“Host mirror stopped because the sync protocol version does not match the server. …”と出る。next_actionsはaachat updateを示す。aachat upは通常の停止・保存処理の後に一度だけ自動更新し、入った版が実行中と違えば同じ引数で自分を再起動する。最後に同期できたProjectファイルは残るが、最新ではない。自動更新で解消しなければaachat updateを実行し、人間にaachat upを再起動してもらい、aachat statusで確認する。途中で止まったSessionの続きは人間が判断する。

起動時の自動更新で止まる

~/.cargo/bin/aachat（CARGO_HOMEを設定していれば$CARGO_HOME/bin/aachat）として起動したaachat upは、runtimeを起動する前にaachat-updateで自分を更新する。新しい版が入るとRestarting with the updated binary...と表示し、同じ引数で起動し直す。最新ならaachat v<版> (up to date)と表示して続ける。この起動時の更新が失敗すると、aachat upはruntimeを起動せずに終了する。

起動後も、実行中のturnがないときに1時間ごとに更新を確認する。この確認が失敗してもUpdate check failed: …と表示されるだけで、runtimeは止まらない。

切り分けるときはaachat updateを実行する。成功するとdata.update.dispositionがinstalledまたはup_to_dateになる。失敗時はerrorとdata.change.stateを読む。

• not_applied — 準備（aachat-updateの確認、現在の版の読取）で止まった。何も変わっていない
• unknown — updaterを実行した後に失敗し、入った版を確認できていない。data.gapsに未確認の項目が出る。aachat --versionで現在の版を読む

入れ直しは公式installerで行う。Reinstall with:が示すGitHub Releasesのaachat-installer.shと同じinstallerである。

curl -fsSL https://aachat.io/install | sh
aachat --version
chat --version

成功の判定：aachatとchatが同じ版を返し、aachat upの再実行でup.logのLaunch Reportまで進む。

aachat upの代表的なメッセージ

Launch Reportの[failed] <agent>の下には、Error [<カテゴリ>]: <メッセージ>、原因の行、Hint:の行が出る。上のカテゴリ表より先に、メッセージで次の表を引く。Hint:に具体的な操作が書かれている。

runtime adapter（Node.js・npm）

aachat upはClaudeとCodexのruntime adapterをnpm ciで準備する。片方だけ失敗した場合、agentは準備できたRuntimeだけで起動する。両方とも失敗すると、そのagentはno supported runtime adapter could be materialized (…)で[failed]になり、括弧内にRuntimeごとの理由が並ぶ。

ghとaachatのサインイン

aachat upはAuthenticating...の段階で、保存済みのaachatのサインインが無効ならgh auth tokenから更新する。ここで失敗するとLaunch Reportの前に止まる。

git（agent repoの取得）

gitの出力に次の語句が含まれると（大文字小文字は区別しない）、該当するHint:が付く。

runtime lock

通常のaachat upは、既に動いているaachat upを止めて置き換える（Stopping existing aachat up (pid <pid>)...）。--if-stoppedは動いていれば何もしない。

対処は共通である。aachat statusのdaemonとaachat launcher statusで、どこで動いているaachat upかを確認する。ターミナルで起動したものはそのターミナルでCtrl+C、macOSのlauncherが起動したものはaachat launcher stopで止めてから、aachat upを再実行する。lockやstatusのファイルを手で消して回避しない。解消しなければaachat supportを起動する。

layout移行が必要と言われる

project workspace layout migration required で止まる場合は、CLIを更新してから aachat support を起動する。旧ルートをそのまま保管し、空のルートに切り替えて、同じTeamへ接続し直す。旧形式を使い続ける互換モードはない。

メッセージと復旧で用意される空のルートは、どちらも layout 8 である。すでに layout 7 のルートは移行を求められない。次に通常どおりSessionが起動すると、membershipを確認したうえでlayoutの記録だけを layout 8 へ更新する。ファイルは動かさない。

supportは、homeと接続済みrepositoryの一覧・元のTeamを記録し、runtimeと旧Sessionの停止を確認してから切り替えを行う。aachat support recover-layout --root <絶対パス> --backup <新しい保管先の絶対パス> は確認のみで、同じ引数に --apply を付けると旧ディレクトリ全体を保管先の old-root へ移し、新しいルートを用意する。保管先は同じfilesystem上で、Git repository・home・対象ルートの外に置く。対象はaachat homeまたはrepository内の aachat ディレクトリであり、repository自体やSession workspaceではない。対象の外から実行する。実行中のruntimeや既存の別の保管先がある場合は拒否する。

中断時は同じroot・backupで再実行する。recovery.json と旧ルートを削除せず、予期しないファイルがある場合は上書きしない。準備の成功は復旧完了ではない。すべての対象を切り替えてから、aachat auth login、各repositoryで元のTeamへの aachat init --team <元のslug>、Team IDの照合、aachat env --interactive によるSecrets設定へ進む。古いtoken・同期状態・journal・env.toml は新ルートへコピーしない。

Linux/WSLでは人間がterminalで aachat up を起動し、macOSでは既存のlauncherの手順を使う。supportがruntimeと新しい同期を確認する。未同期の編集は、保管した旧baseline・編集済みファイルと新しく取得した内容を比較して回収する。旧Session worktreeや成否不明のMedia・外部処理も保管されるため、結果を照合するまで再送しない。ローカル作業の回収が済むまで保管先を残す。

認証で失敗する

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

aachat auth status
aachat doctor

aachat doctorのdata.diagnostics.issues[]でよく出るものは次の2つである。

• user_jwtがfail（User JWT: expired） — aachatのサインインが期限切れ。aachat auth loginはローカルのghトークンから短命のJWTを発行するため、ghが認証済みなら対話なしで完了する。通常のaachatコマンドを実行しても更新される
• github_authがunknown — 未認証とは断定できない。gh auth statusで確認する。github_scopesがfailなら確認済みのscope不足を読み、人間がgh auth refresh -s repo,read:userを実行する

chatが動かない・版が合わない

chatはSession内のagentが使うCLIで、aachatと同じ場所（通常は~/.cargo/bin）に入る。aachatとchatは同じ版である必要がある。

command -v chat
chat --version      # chat <版> と表示される
aachat --version

• chat --versionが何も出さない、または別のプログラムが動く。 macOSには標準で/usr/sbin/chatという別のコマンドがある。PATHで/usr/sbinが~/.cargo/binより前にあると、そちらが動く。command -v chatが/usr/sbin/chatを返したら、shellの設定で~/.cargo/binをPATHの前に置くか、~/.cargo/bin/chatを直接指定する。Session内のagentには、aachatが正しいchatのあるdirectoryをPATHの先頭に入れるため、この問題は人間のterminalで起こる
• 版が違う・chatがない。 aachat upはcompanion version mismatchやcompanion is missing or not an executable regular fileで止まる。aachat doctorではchat_companionがfailになる。公式installerで入れ直す（上の「起動時の自動更新で止まる」）
• token_required（Run this command inside aachat up or set AA_TOKEN_FILE or AA_TOKEN.） — chatをSessionの外で実行した。chatはSession内のagent用である。人間やSession外のエージェントはaachatを使う（CLI）
• session_required — Sessionが必要なコマンドを、AA_SESSION_IDがない環境で実行した。同じくSession内で使う

WindowsとWSL2で使う

aachatのCLIはmacOSとLinux向けにだけ配布される。Windowsでは、WSL2（Ubuntu）の中でセットアップの手順を使う。Windows向けのinstallerはない。

WSL2では、aachat doctorが次の2つを確認する。

どちらも、確認のコマンドが失敗したときはunknownになる。unknownは未設定の証拠ではない。aachat upはOSのサービスとして自分を登録しないため、常駐はそのマシンのプロセス管理で行う。

環境変数がagentに渡らない

APIキーなどが届かず、agentが「キーがない」と報告する症状。値そのものは表示せずに状態を確認できる。

aachat env list

各itemのstateとmissing_reasonを読む。

• value_missing — 宣言した名前がbinding先に存在しない。Tools > SecretsでComputerを選び、Keychainまたは.envへ登録する。
• approval_missing — そのAgentへ名前を渡すbindingがない。Tools > Secretsで、そのAgentの行のAllowから許可する。宣言だけでは許可されない。
• provider_unavailable — 保存先を取得できない。選択したComputerの.envのpath/権限またはlogin Keychainの状態を確認する。取得失敗はunknownで、不存在の証拠ではない。
• provider_removed — Agent環境変数のInfisical連携は廃止した。外部CLIを起動せずfallbackもしない。認証済み人間のterminalでaachat env adoptを実行し、Keychainまたは.envへ明示登録・使用許可する。
• Local setup required — 旧設定や既存.envは対象Computerでaachat env adoptによる確認が必要。WebUIは自動claimしない。

変更は次にAgentが環境解決を始めるときから反映し、準備済み・稼働中processは変わらない。値保存の結果が不明なら次の変更前にRefreshし、自動再送や存在だけによる前回成功判定をしない。値保存が確認済みで許可だけ失敗した場合は許可だけを再操作する。詳細はEnvironment。

Session

Sessionが起動しない

chat session runやtarget chipへの依頼でSessionが始まらない症状。

chat session runとWorkflow Runの作成は、新しいSessionがstartingを抜けるまで最大40秒待ち、結果をCLIのJSON出力のdata.startup（Workflowではdata.startups[]の各startup）で返す。まずstartup.stateを読む。

Sessionそのものが作られない場合は、次の条件を順に確認する。

1. Projectのstatusが In progress（active）か。 Sessionを実行できるのはactiveなProjectだけである。違えばproject_not_activeになる
2. agentがそのProjectのmemberか。 session runのagentはProject memberとして解決される。memberでなければProjectに追加する
3. agentのowner側でaachat upが動いているか。 agentのruntimeはownerのマシンで動く。接続状態はWebUIのagent表示またはaachat agent listで確認する。agent_runtime_offlineなら人間にaachat upを起動してもらい、agent_runtime_project_unavailableならaachat upの再接続かagentのProject membershipの更新を依頼する。dormantのagentはaachat upの起動対象から外れているため、aachat agent update <name> --no-dormantで戻す

Sessionが止まって見える

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

• 許可待ちを確認する。 agentは影響の大きい操作の前に実行許可を待ち、回答があるまで待ち続ける。WebUIの許可ダイアログで許可または拒否を選ぶ。CLIではaachat session permission list <session-id> --project <project>で待っている要求を読み、aachat session permission respondで答える
• @mentionだけで送っていないか確認する。 正確な@<agent>.<owner>は通知であり、Sessionの実行トリガーではない。target chipで宛先に指定するか、session runを使う（Sessions）
• live表示の状態を確認する。 live表示はSessionの画面を開いている間だけ届き、テキストとtoolの要約だけを表示する。Live view is unavailable with this version.はruntimeの版が古い（Desktop）。Update instructionsに従ってaachatを更新し、Retryを押す。Live updates could not keep up.やCould not update the live view.は表示の問題であり、Sessionの失敗を意味しない。Retryで読み直すか、保存された履歴を読む

許可への回答がagentに届かない

許可ダイアログで答えた後に、配送待ちや失敗が表示される症状。回答自体は保存されている。

1. Refresh statusで配送の状態を読み直す
2. 配送待ちなら、runtimeが接続してからRetry responseを押す
3. runtimeが受け付けられない状態なら、Session ownerがStop nowで止め、SessionがstoppedまたはfailedになったらRestart sessionで再開する。owner以外はownerへ依頼する

同じ回答を別の方法で重ねて送らない。

Sessionが失敗した・途中で止まった

Sessionがfailedになったり途中で停止しても、それまでの仕事は消えない。

WebUIのSession画面では、failedのSessionに失敗の理由が出る。serverが理由を記録していればその文（Runtime error: …など）、起動準備の段階で失敗した場合は失敗した準備の内容、操作がruntimeへ届かなかった場合はA control command didn't reach the runtime. …、終了を確認できなかった場合はCouldn't confirm shutdown. Check the agent logs.が出る。どれにも当たらないときはRuntime failed. Check the agent logs.と出る。agentのログはownerのマシンにある。ownerがaachat session logs <session-id> --from-startで読む（ログを見たい）。owner以外は、Session IDと時刻を添えてownerへ依頼する。

• 会話の記録は残る。 Session recordとtranscriptはserverに保存されており、aachat session read <session-id> --project <project>で確認できる
• Projectに残した分は次の入力になる。 そのSessionがShared Documents・Project Chatに残した成果物と判断は、次のSession（同じagentでも別のagentでも）がそのまま読める

runtimeがturnを実行できなかった場合： Sessionはすぐにfailedになり、workspaceは保持され、「このrequestの結果は確認できない。自動では再実行しない」という趣旨のエラーが出る。入力がagentへ届いた可能性があるので、同じ依頼をそのまま再送しない。runtimeが止まったことを確認し、保存済みの履歴と、ファイル・push・PRなどの副作用を確認してから、新しいSessionで続ける。ownerのマシンではaachat session logs <session-id> --from-startでagentのstderrを読める。

同じSessionを再開する場合： 同じ仕事を続けられるstopped・failedのSessionは、Session ownerがWebUIのRestart sessionで再開できる。Session agentはchat session send <session-id> --project <project> --resume "追加指示"を使える。ownerでない人は、そのどちらかへ依頼する。starting・stoppingの間は待ち、再開を重ねない。archivedのSession、Workflow Step、workspace・設定・Project coverageを復元できないSessionは再開できない。その場合は必要な成果を新しいSessionへ引き継ぐ。

Workflow Stepなら Runを開き、available_actions.retry_stepsに示されたStepだけWorkflowのretryを使う。Published Workflow Stepの失敗はchild Runを開いて失敗した内部Stepをretryする。retryは新しいAttemptを作る操作であり、Sessionの再開は使えない（Workflows）。

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

runtimeが再起動しても、agentが実行を始めたturnは自動では再実行されない。実行が始まる前に受け付けられていた依頼は、条件がそろえば同じSessionへ再配送される。

1. 元Sessionを開き、受付turnと保存済みtranscriptを読む。startingなら回復中の可能性があるため、run/sendを重ねず次の状態を確認する
2. 成果文書、working tree、push・PRなどの提出、外部操作の結果を確認し、既に実行された仕事を切り分ける
3. 回復が止まったら、元Session/Run ID、受付turn、時刻、Project status、エラーcode、利用版、既存の成果をそろえて管理者へ伝える。403などの拒否は対象Projectと権限を確認し、状態を読み直すまで操作を繰り返さない

ClaudeやCodexのエラーでSessionが失敗した

既知の利用上限・認証失敗は、部分結果の保存後、同じSession・Workflow Attemptで自動復旧を待つ。Runtimeの復旧を参照。課金・プロバイダの一時的な拒否（Codexのrate limit・容量不足・HTTP 429による内部再試行の枯渇を含む）は手動待機となり、Retryで一回だけ再試行する。履歴欠落・未解決実行・結果不明による安全停止はRetryでは解除しない。明示的なCompactの失敗は通常作業の継続へ変換しない。

分類対象外のprompt失敗では、従来どおりSessionがfailedになり、次の形のエラーが残る。WebUIのSession画面、またはaachat session read <session-id> --project <project>で読める。

Runtime error: <providerの文言> (JSON-RPC error <code>). The result of this request could not be confirmed. It will not be replayed automatically. The workspace is preserved. Confirm that the runtime has stopped, then review the saved history before continuing in a new Session.

復旧allowlist対象外の失敗は<providerの文言>を読んで原因を切り分ける。送信・保存の結果が不明なら自動でpromptを送らない。Claudeの利用上限やAPIのエラーはInternal error: <Claude Codeの文言>（JSON-RPC error -32603）として届く。

再送の前に、上の「Sessionが失敗した・途中で止まった」の手順で、保存済みの履歴とファイル・push・PRなどの副作用を確認する。入力はagentへ届いた可能性がある。

providerのログインを確認する

aachat doctorはproviderを検査しない。provider_readinessは常にskipped（Provider readiness is not checked. No provider login or model call was performed.）であり、healthyでもログイン済みとは限らない。

runtimeを動かすマシンで、aachat upと同じユーザーとして確認する。

claude auth status    # Claude
codex login status    # Codex

• Claude runtimeは、起動時のCLAUDE_CONFIG_DIRのログインを使う。環境変数がなく、~/.claude/settings.jsonのenv.CLAUDE_CONFIG_DIRに絶対pathがあれば、そのdirectoryを使う。この場合はCLAUDE_CONFIG_DIR=<そのpath> claude auth statusで確認する
• ログインし直すのは人間である（claude auth login、codex login）
• WebUIのUsageでも、端末ごとのログイン状態と利用枠を確認できる。未ログインならSign in to this provider on this computer.と出る。Agentの環境設定は適用しないため、Agentの環境変数で渡したAPIキーの状態はここに出ない

成功の判定：provider CLIがログイン済みを示し、新しいSessionの最初のturnがRuntime errorなしで応答する。

Sessionの準備段階で失敗した

Sessionはturnを始める前に、agent processの起動、Runtimeとの初期化、Runtime設定の適用などを行う。ここで失敗すると、WebUIのSession画面にエラーとInitialization step: <step>が表示される。chat session runではstartup.stateがfailedになり、startup.error_messageに同じエラーが入る。

同じGit cacheを使うSessionがある場合、起動はlock取得まで待機し、その間もheartbeatを続ける。待機時間だけで一律60秒後に失敗することはない。取消後は実行中のGitの停止確認を待つため、即座に終了するとは限らない。lockファイルを削除して待機を解除しない。

stderrはownerのマシンでaachat session logs <session-id> --from-startで読む。空き容量不足（workspace_capacity_insufficient）は下の「空き容量不足でSessionが始まらない」へ進む。

この段階の失敗では、最初の依頼はagentへ送られていない。最初のmessageの配送エラーとして、準備の失敗はSESSION_BOOTSTRAP_FAILED（文言は上の表）、それ以外で最初のturnより前に失敗した場合はSESSION_START_FAILED（… Fix the runtime setup, then start a new Session to try again.）が記録される。CLIではaachat session read <session-id> --project <project> --submission <turn-id>のsubmission.errorで読める。最初のmessageの下にStart a new Sessionが表示される場合は、押すと同じ依頼文と添付を引き継いだ新しいSessionを準備できる。手元からの添付ファイルは再uploadが必要である（Upload this file again before sending.）。原因を直してから使う。

Runtime設定が拒否された

Session開始時に指定した設定option（モデル・モード・強度など）をRuntimeが受け付けないと、stepはlaunch_configになり、promptを送る前に失敗する。

codeはWorkflow Stepの失敗に表示される（Workflows）。

1. 現在のprofileを読み直す。人間は起動フォームのRuntime settings、Session内のagentはchat project members <team>/<project> --runtime-profilesを使う
2. --configで指定した値が原因なら、提示されている値に直すか外す。agentの既定値が原因なら、Unavailable agent defaultsのRemove from agent defaultsで外す
3. config_not_provenが続く場合は、aachat updateでruntimeを更新し、人間にaachat upを再起動してもらう
4. 新しいSessionを始める。agentの既定値を変えても、失敗したSessionの設定は直らない

詳細はAgents。

runtimeの終了・切断でSessionが失敗した

Session画面またはSessionのerror_messageの文言で切り分ける。どの場合も、それまでの記録と成果は残る。再送の前に、上の「Sessionが失敗した・途中で止まった」の手順で履歴と副作用を確認する。

• 実行中のturnがなかったSessionは、aachat upの再起動後にstoppedとして閉じられ、エラーは残らない。ただしchat session finishの後でstoppingだったSessionは、agent runtime process changed while this session was active. …のfailedになる。startingのSessionは回復の対象であり、上の「runtime再起動の後に同じ仕事を送る前に」に従う
• 許可への回答を待っている間は、60分の期限は延びる
• 終了時に… Session task was aborted before child process exit could be confirmed.、… Child process exit was not confirmed; …が付いた場合は、processの停止を確認してから次の仕事を送る

操作がruntimeへ届かない

follow-up、取消、Finish・停止、Runtime設定の変更、許可への回答は、serverからownerのruntimeへ配送される。配送失敗またはACK未確認でSESSION_COMMAND_UNDELIVEREDが返り得る。messageはSession command could not be delivered to the runtime.で始まり、続く文で状況がわかる。codeだけでは未到達と断定できない。

同じ配送でも、runtimeが接続していなければAGENT_RUNTIME_OFFLINE、接続しているがそのProjectを受け取っていなければAGENT_RUNTIME_PROJECT_UNAVAILABLEになる。対処は上の「Sessionが起動しない」と同じである。

1. Sessionを開き直し、状態を読む。follow-upならturnとして受け付けられていないか、取消・停止なら状態が変わっていないかを確認する
2. runtimeの接続をWebUIのagent表示またはaachat agent listで確認する。切れていれば、人間にaachat upを再起動してもらう
3. 届いていないと確認できた操作だけを、一度だけ再送する。許可への回答は上の「許可への回答がagentに届かない」の手順を使う

SessionがfailedでA control command didn't reach the runtime. Check the runtime logs, then retry the command after the runtime is healthy.と表示される場合は、runtimeがそのSessionを受け取れない状態だったため、Sessionを止めた。runtimeのlog（aachat statusのdaemon.log_path）を読み、runtimeが正常になってから操作するか、新しいSessionで続ける。stoppingのままA previous close delivery attempt failed. The stop request remains accepted while terminal confirmation is pending.と出る場合は、停止要求は受け付け済みである。停止を重ねて送らず、停止の確認を待つ。

chat session runで起動の配送が失敗した場合は、error.codeがsession_command_undeliveredになる。runtimeを再接続してから再実行する。

空き容量不足でSessionが始まらない

Fresh SessionやWorkflow Sessionがworkspace_capacity_insufficientで失敗した場合、toolの実行やworkspaceの作成は始まっていない。開始前に20 GiBの空きを確認し、足りなければ同じagentの非稼働workspaceを一度だけ整理した後の結果である。

1. aachat statusのwarnings[]（session_workspace_capacityなど）とnext_actionsを読む
2. aachat doctorで保持されたworkspaceのpathと理由を読む
3. 保持されているworkspaceに未commitの変更やpushしていないcommitがあれば、先にcommit・pushするか別の場所へ保存する
4. doctorが示す操作に従って空きを作り、新しいSessionを始める

検索や履歴に見当たらない

• 検索結果が短い。 query指定のメッセージ検索は、一致箇所の周辺だけを最大240文字の抜粋で返す。全文は結果から該当messageへ移動するか、chat readで読む
• 起動時の指示が見つからない。 Triggerが起動したSessionの最初の指示はメッセージ検索の対象外である。元Sessionのtranscriptで確認する
• 1 Session内を探したい。 chat session read <id> --project <project> --match <text>で文字列を探す。成功した空の応答は、指定したProject・範囲に一致がないことだけを示す。403・404・timeoutは読み取りの失敗である
• Toolの出力がない。 新しく保存する履歴とlive表示では、toolの入力と状態に加え、対応する完了済み出力の末尾最大2,000文字（Unicode文字）だけを扱う。出力全文、diff本文、実行中だけ届いた出力、値のない過去の履歴は復元されない。出力がないことだけで実行の成否を判断しない。最終応答やShared Documentsなどの実際の成果と照合し、欠けた出力を埋めるためだけに実行を繰り返さない（Sessions）

ログを見たい

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

Sessionの終了前後で操作が拒否される

chat session finishが受け付けられると、Sessionはすぐにstoppingになる。現在のturnが終わると、成果を整理するturn（Asset Wrap-Up）が一度だけ走り、Sessionは閉じる。finishの後は、同じturnの残りでも、多くの操作がsession_not_runningで拒否される。

finishしてからAsset Wrap-Upが始まるまでの間に文書を保存すると、permission_denied（理由session_closing）で保存されず、ローカルの変更は未保存のまま残る。Asset Wrap-Upで保存し直す。

正しい順序： Askの作成、wait登録、委任、必要な保存と成果の報告をfinish前に済ませる。残りの仕事が登録成功したwaitから進めるものだけの通常Sessionは、親へ返す最終結果が未完成でなく、開いておく個別契約もなければchat session finishで終了できる。未完了の子SessionとWorkflow Attemptは待つ間turnだけを終える。終了後も未成立waitは残り、各waitの全targetが確定すると同じSessionで継続する（終了条件）。

成果の報告が記録されない

chat result reportは、項目ごとに記録する。1つでも記録されないと、全体はresult_report_incompleteで失敗する。記録された項目は保存済みである。

1. data.items[]で、statusがerrorの項目のcodeとmessageを読む
2. data.retry_fileがあり、data.retry_file_stateがstaleでなければ、chat result report --retry-stdin < <retry_file>で同じ内容を再送する。payloadを書き換えない
3. retry fileに入らない項目は、下の表に従って直し、その項目だけをchat result report --stdinで送り直す
4. PRの作成やpushなど、元の操作は繰り返さない

result_retry_persistence_failedでは、再送前にdata.mutation_stateとdata.retry_file_stateを読む。

• not_applied：記録要求は送信前に止まった。workspaceへの書込みを復旧し、返されたdata.retry_payload全体を改変せず保存してchat result report --retry-stdinの入力にする。これは固定retry envelopeであり、通常のresults batchへ組み替えない。他にローカルで失敗した項目はdata.items[]のcodeに従って別に扱う
• stale：送信後にfileを更新できなかった。data.items[]の成功分は保存済みとして保ち、元batchを再送したり、staleなretry_fileを残batchとして使ったりしない。mutation_stateがappliedでretry_payload.itemsが空なら再送不要。partially_appliedまたはunknownで残項目があれば、最新のdata.retry_payload全体を改変せず別fileに保存し、書込み復旧後に--retry-stdinの入力にする。unknownを未適用と読み替えない

retryするのは固定payloadの残項目だけである。それ以外の失敗項目は個別のcodeとmessageに従い、payload外の全項目を自動で再試行したり、元のPR作成・pushを繰り返したりしない。

要求全体がsession_not_runningになる場合は、Sessionが実行を受け付けたturnの外から報告した。終了処理の後や、背景の通知で再開したturnでは記録できない。報告できなかった成果は、最終回答で明示する。手順の詳細はコードの提出とCLIを参照する。

Project・権限

Projectや文書が読めない

別のProjectを読めない・変更できない

Session内のagentが扱えるProjectは、Sessionのcoverage（対象範囲）で決まる。coverageには、Sessionを起動したProjectが入る。agentがそのProjectのLeadなら、activeな親Projectと子Projectのうち、agentがviewer以外の権限でmemberであるものも入る。chat project joinで参加したProjectも加わる。書き込みには、coverageに加えて、collaborator以上のmembershipとProjectのstatusがactiveであることが必要である。

aachatでは、not_authorizedの代わりにpermission_deniedが出る。WebUIで同じ制限に当たると、Read-only accessのように表示される。権限の全体は権限を参照する。

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を選ぶ。dormantのagentは候補に出ず、指定するとThis agent is dormant. Choose an active agent as the Project Lead.で拒否される。先にaachat agent update <name> --no-dormantで戻す。子Projectなら親がactiveで、自分が親のAdminまたはcurrent Leadである必要がある。詳細条件はProjectsを参照する。

受付後に応答がない、または通信エラーで作成できたか不明なら、先にProjectsで作成済みか確認する。agent Leadなら受付されたSessionを確認し、同じ依頼を重ねる前に上の「Sessionが起動しない」へ進む。

REPORT不足でDoneにできない

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

通常のProject文書の権限で、正確なaachat/teams/<team>/projects/<project>/docs/REPORT.mdへ成果・確認した根拠・残る差を保存する。Docsで同期済みの本文を確認し、成果を受け入れてからAdminがDoneを再試行する。空の文書、別名のreport.md、planningへの変更で条件を回避しない。保存済みなのに同じ拒否が続く場合は、下の「Shared Documentsが同期されない」を確認する。

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

確認前に止まる場合： Project Adminであることと、対象がplanning / active / completedであることを確認する。確認画面に出るactiveな子Projectは、成果確認後にDoneにするか、親を付け替えるか、影響を確認してArchiveする。通常SessionでもWorkflow Sessionでも、このProjectと別のProjectの両方を扱うSessionがあると“A Session also covers another Project. Finish that Session before archiving.”で拒否される。そのSessionを終えてから確認を開き直す。確認後にTrigger・予約・Run・Sessionが変わると“Archive confirmation changed. Refresh and confirm again.”で拒否されるので、画面を開き直して最新の件数・対象を確認する。Archive confirmation requiredが出た場合は、SettingsのArchiveから確認を開く。

親の付け替えで止まる場合： project_reparent_status_conflictは、付け替える子がplanning / activeでない、または新しい親がactiveでない場合のエラーである。子または新しい親がArchive処理中ならArchive is in progress.で拒否される。Archiveの完了を確認してから付け替え先を確認し直す。

受付後に進まない場合： Archiveは非同期で、未完了のWorkflow Runを取り消し、このProjectを扱う通常SessionとWorkflow Sessionの両方の停止を待つ。Projectを開き直し、Archive in progressの残りRun数と停止待ちSession数を見る。Could not complete Archiveが出たらエラーcodeと示されたRun・Sessionを開き、問題を確認したうえでAdminがRetryを選ぶ。

Retryの受付も完了ではないため、Archivedになったことを確認する。CLIではaachat project update <name> --status archived --cancel-runsで未完了のRunを取り消してArchiveできる。端末（TTY）では確認の[y/N]が出る。非対話で未完了のRunがあるのに--cancel-runsを付けないとconfirmation_required（change.state: not_applied）で何も変わらない。--cancel-runsは--status archivedと一緒にだけ使え、descriptionやLeadの変更とは同時に送れない。

status変更・削除・親の付け替えで処理中のArchiveを迂回しない。解消しない場合は、Team / Project、発生時刻、status、残りRun数・停止待ちSession数、エラーcodeとmessage、示されたIDを管理者へ伝える。復帰後も取り消した仕事は自動では戻らない（Projects）。

Project削除が失敗した

削除はplanning / active / completed / archivedのどのstatusからでも受け付けられる。Archive処理中は“Archive is in progress.”で拒否されるので、Archiveの完了を先に確認する。子Projectがある場合は、すべての子を先に付け替えるか削除する（“Reparent every child Project before deleting this Project.”）。

Projectの削除は非同期で、WebUIにDeleting / Deletion failed / Retryが表示される。Deletion failedならerrorを確認し、同じProjectのRetryから再開する。新しい同名Projectを作って回避しない。削除前に戻したい場合はdeleteではなくArchiveを使う（Projects）。

GitHub repositoryを接続できない

Team SettingsでGitHub App経由のrepositoryを一覧・接続するには、サインインしている人のGitHubアカウントがそのrepositoryを読めることが必要である。

• Your linked GitHub account must have read access to this repository. — このrepositoryへの読み取り権限を持つアカウントで接続するか、権限をもらう
• Your linked GitHub account cannot read any repository shared with this GitHub App installation... — GitHub Appに共有されたrepositoryを1つも読めない。repositoryへのアクセスを依頼するか、接続すべきGitHubアカウントでサインインし直す

GitHub Appのinstallから戻ったときに次のtoastが出たら、接続は完了していない。

• GitHub App installation was not completed. Try again. — GitHub側でinstallが終わらなかった。Team SettingsのConnect GitHub repositoryからやり直す
• installから戻ったときにAgentsの画面（/home/agents）が開き、Team Settingsに何も表示されない — 接続の途中の情報が期限切れか、すでに使われていた。Team SettingsのConnect GitHub repositoryから最初からやり直す

接続の手順はConnected Repoを参照する。

Askと待機

Askへ回答したが続かない

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

1. Answeredに回答があるか、revisionとChange historyを確認する。選択肢を選んだだけならdraftなのでSave answer / Save onlyで保存する。回答できるのは担当者またはProject Adminである
2. source Sessionを開く。Awaiting resultsからcomposer上の待機パネルを確認できる。対象を展開し、未確定の別Ask・Session・Runを確認する。Couldn't load wait details.ならパネルのRetryで読み直す。これは配送の再試行ではない。Session agentはchat wait show <wait-id> --project <team>/<project>で待機を読める（CLI）
3. Askの回答や取消から継続までは、次の30秒周期の確認まで遅れることがある。その間にpolling、再登録、手動送信を重ねない。Wait completedが出たら展開して各結果を確認する。Needs attentionは失敗・要確認・取消の対象があるという意味で、回答保存の失敗ではない
4. 通知の配送を別に確認する。Delivery pendingは配送待ちである。Delivery failedでは通知を展開してエラーを読み、原因を解消してからRetry deliveryを使う。Sessionがrunningで接続中である必要がある。Retry requires a running Session.なら先にSessionを復旧する。Delivery cancelledは配送されていない。sourceを復旧または置き換えた後、保存済み結果のリンクかIDを含むfollow-upを一度送る。Workflow Stepなら上のWorkflowの復旧手順を使う
5. 配送が進んだら、次のturnと保存済み回答を使った成果を読む。通知の保存や受付だけで成果が出たと判断しない

待機が登録されていない通常のProject Askは、保存だけでは新しいturnを起動しない。継続が必要なsourceがrunningなら、保存済み回答を手動のfollow-upで一度送る。

Answer saved. The session will continue when all wait conditions are met.は保存済みで条件待ち、Chat continuation acceptedは自動継続が受け付けられたことを示す。後者でもagentの読了や成果は未確認なので、source Sessionの次turnを読む。Send N answers to sessionの件数は自動対象を除いた数であり、少なくても保存失敗ではない。取消は確定（settled）だが承認ではない。後から回答を変えても同じ待機は再発火しない（Projects、Sessions）。

Automatic continuation cancelled before delivery. Answer saved. が出た場合は、Open sessionで開き、必要なら明示再開し、runningになってから保存済み回答を送る。Couldn't confirm submission. Answer saved. は送信の受付結果が不明という意味で、Resendは同じ要求を再試行する。受付は配送・読了の証明ではない。Askの回収手順を参照。

解決しなければProject・Session・Ask・wait ID、回答revision、状態、エラーと時刻をそろえて調査へ渡す。

文書・HTML・Media

Shared Documentsが同期されない

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

aachat status

• projection.stateがerrorなら、projection.reasonに原因（例: “Mirror has one blocked write: …”、“Mirror has N unresolved diagnostic files.”）が出る。原因ファイルはProjectの_errors.mdに並ぶ。自動生成される_errors.mdは編集せず、書かれた原因ファイル側を直す。詳しい項目はaachat doctor --view checksで読む
• blocked write（直すまで送られない書き込み）は、衝突マーカーが残ったファイルや、競合中に消えたファイルである
• Sessionのworktreeでは、aachat upのdaemonではなくそのSession自身のmirrorが同期する。projection.reasonにその旨が出る

ローカルの編集がserverの新しい版と衝突した場合： mirrorはbaselineとの三者mergeを行う。重ならない編集は自動でmergeして送り直す。同じ箇所の編集は送られず、serverの版がそのまま正本になり、ローカルファイルにdiff3の衝突マーカー（ours＝ローカル、original＝共通の祖先、theirs＝server）が書き込まれる。_errors.mdにそのファイルが載る。

1. そのファイルのマーカーをすべて取り除き、残したい内容にする（fenced code block内のマーカーは対象外）
2. 同じpathに保存する
3. aachat statusのprojection.stateがerrorでなくなり、_errors.mdからそのファイルが消えたことを確認する

code fenceの外にある、<・|・>のいずれかを7個以上並べた行は衝突マーカーとみなされ、uploadが止まる。ファイルを削除・移動しても文書の削除にはならない。削除したい場合は先に衝突を解消し、その後通常の方法で削除する。未解決の衝突が残っている間は、Sessionの完了も止まる。仕組みはShared Documentsを参照する。

.DS_Store、.localized、Thumbs.db、ehthumbs.db、ehthumbs_vista.db、desktop.iniという名前の通常ファイルは同期の対象外で、起動を止めない。同じ名前のdirectoryやsymlinkは除外されない。

Shared Documentsの正本はserverであり、ローカルのaachat/teams/<team>/projects/<project>/はprojectionである。同期はaachat upが動いている間だけ行われる（信頼境界）。形式の検査はShared Documentsを参照する。

Project HTMLが同期されない・表示が古い

html/_errors.mdを読み、ファイルごとの理由を確認する。

• 5 MiBを超えるファイル — upload前にそのファイルだけが拒否される。他のファイルの同期は続くが、そのファイルを参照するページは正しく表示されない可能性がある。縮小または分割して保存し直す
• 同じファイルの同時編集の衝突 — 解消できない衝突は、双方の編集と共通の祖先が衝突マーカー付きでファイルに残る。採用する内容に直して同じpathに保存する。未解決のファイルはuploadされず、Sessionの完了も止まる。他のファイルの同期は続き、配信中の版は維持される。baselineや_errors.mdを編集して解消しない
• 表示が古い — sourceの同期後に配信用snapshotのrebuildが失敗すると、以前の正常なsnapshotが表示され続ける。rebuildのstatusとerrorを確認し、原因を直す。aachat upの同期状態だけで表示が更新されたと判断しない
• Mediaが見つからない・準備中 — buildのエラーが最初の参照と(and N more)を示す。参照先のMediaがreadyになればHTMLは自動でrebuildされる。Mediaが存在しない・失敗・削除済みなら、代わりのMediaを公開する（path参照なら同じpathで、ID参照なら新しいIDに書き換えて同期する）

詳細はHTMLを参照する。

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

chat media <project> --download <media-id>は内容をmedia/.downloads/<media-id>.<ext>へ書き出す。

• media_unavailable — そのMediaはまだreadyでないか、このProjectのものではない。commandsのchat media <project>でreadyなMediaの一覧を確認する
• media_download_failed — ファイルは書かれていない。reasonを読んで一度だけ再試行し、再び失敗したらchat reportで報告する

成功のJSONなしに内容を推測したり、残っている同名ファイルを今回の取得結果としたりしない。canonical URLをfetchしても内容ではなくログインページが返る。参照にはcanonical URLを使い続け、取り出したコピーを再公開しない（Media）。

古いaachat.workのリンクが開かない

旧ドメインのaachat.workは廃止された。WebUIのページへのGET/HEADは同じpathとqueryのままaachat.ioへ転送されるが、API・Media・HTMLのshare・画像・hooksは403を返す。履歴や文書に保存された古いリンクは自動では書き換えられない。WebUIのページはaachat.ioの同じpathへ置き換える。Mediaのリンクはhttps://aachat.io/m/<uuid>へ置き換える。HTMLのshare URL（h<key>.html.aachat.work）は、ProjectのHTMLのShare HTMLから現在のURLをコピーし直す。

Agentとskill

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

応答が、Projectのこれまでの決定・成果を無視しているように見える症状。agentがSession開始時に読む文脈の経路を順に確認する。

1. ProjectのPROJECT.md — 安定したPurpose、Outcome、Success Measures、Required Outputs、判断原則・境界、Context Mapが書かれているか。無い、または古い場合は整備する。進捗・指標の現在値・担当・handoff・ログで更新しない
2. Context Mapとgenerated index.md — PROJECT.mdのリンクから必要な正本へ進めるか。そこに無い文書は、全件を並べるgenerated index.mdから探す
3. 直前の動的な文脈 — 前のSessionのtranscript、短いProject message、または通常のShared Documentにhandoffがあるか。handoffをPROJECT.mdへ移さない（Shared Documents）
4. agent repoのmemory — Project横断で持ち回るべき経験則がagent repoのmemory/にあるか。無ければ書いてpushする。反映は次のSessionからである

2層構造（agent自身の記憶 / 仕事の文脈）の定義は基本概念を参照する。

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

agent repoを編集したのに、agentの振る舞いが変わらない症状。agent repoの変更は、commitしてpushした後の次のSessionから反映される。動いているSessionには反映されない。変更をpushし、新しいSessionを始める（Agents）。

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

Launch Reportにはworkspace / Platformの衝突、SKILL.mdの欠落、symlink・特殊ファイル・UTF-8でないpathが出ることがある。同名でもsetupを失敗させず、意図的にshadowする場合がある。

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

正本とprecedenceはSkillsを参照する。

Skill Ledgerにsourceや利用記録がない

Skill Ledgerは一覧を開くと接続済みrepositoryを自動確認する。Session起動や手動更新は不要。

1. AgentプロフィールのSkillsタブ、またはTeamのSkills画面を開く。Connect repository が必要ならAgent所有者またはTeam管理者へ接続を依頼する。一時的な失敗は Retry で再試行する。同じ接続の前回分があれば表示するが、切断・失効した保存元の旧本文は表示しない
2. 利用記録とfeedbackは、保存されたtool観測とSessionへ投影されたskillから記録され、snapshotの更新前でも保存される。push前の変更や実行中のSessionには反映されないので、pushしてから新しいSessionで使う
3. 記録が欠けていても、削除や未使用の証明にはならない。詳細はSkillsを参照する

Claude workspace設定でprepareが失敗する

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

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

文書の書き込み直後に検査結果が出ない

ClaudeのWrite / Edit / MultiEditとCodexのapply_patchで書いた文書は、hookが自動で検査する。shellなど他の方法で書いた文書はchat doc check <path> ...（Sessionの外ではaachat doc check <path>）で検査する。severity: errorは同期が保存を拒否し、warningは保存される。hookはwarningでは書き込みを止めない。hookが検査できなかった場合は、未検査で書き込まれたことが表示されるので、aachatを更新する。

PluginのMCP serverがSessionに出てこない

Pluginのmcp.json / .mcp.jsonのserverは、stdio（既定）・http・sseを使える。websocket、未知のtype、足りない環境変数、不正なremote設定、runtimeが対応を示していないtransport（http / sse）は、そのserverだけが省略され、Sessionは続く。${VAR}が解決できない、urlやheadersが不正な場合も同じである。UIやagentへのメッセージは出ず、runtimeのlog（aachat statusのdaemon.log_path）にだけ記録される。設定を直して新しいSessionを始める。

WebUI

WebUIのボタン名・メッセージは、既定のURLでは英語で表示される（/jaで開いたサインインや参加の画面は日本語になる）。以下の英語の文言はそのまま画面で探せる。画面の地図はWebUIの画面と操作を参照する。

サインインできない・サインイン画面に戻される

WebUIはGitHubでサインインする。失敗すると、サインイン画面のSign in with GitHubの上に理由が出る。

DiscoverのcloneやProjectテンプレートの準備の途中では、Clone session expired. Please try again from Discover.やProject preparation connection expired. Return to your saved setup and try again.が出る。表示された場所（Discover、保存した準備）からやり直す。

同じ表示が続く場合は、表示された文と時刻を控えてsupportへ渡す。

接続表示がReconnecting...やOfflineのまま

WebUIはリアルタイム更新のための接続を保つ。接続中は画面右上に点だけが出て、文字は出ない。

Team内の画面では、再接続が5回続けて失敗するとRetry nowが出る。押すと待たずに再接続する。

切断中は次の操作が止まる。

• Project Chatのcomposerは送信できず、Disconnected — reconnecting before sendと出る
• StreamのcomposerはDisconnected — waiting to reconnectと出る
• SessionのStop responseは使えず、Stop response is unavailable while disconnected. Try again after reconnecting.と出る

対処の順序は次のとおり。

1. Retry nowが出ていれば押す
2. ネットワークを確認し、ページを再読み込みする。書きかけの下書きは再読み込みで消えるので、先にコピーしておく
3. Offlineのままなら再読み込みする。サインイン画面に戻ったらサインインし直す
4. 他のサイトは開けるのに再接続しない場合は、VPN・プロキシ・拡張機能がWebSocketを止めていないか確認する

再接続すると、WebUIは切断中の変化を読み直す。切断中に送った操作の結果がわからない場合は、同じ操作を重ねる前に画面で受付を確認する。

agentのRuntimeが接続していないと表示される

agentのRuntimeはownerのマシンでaachat upにより動く。接続していないと次の表示が出る。

agentのアバターがDisconnectedの場合も同じ原因である（WebUIのagentの状態）。

Sessionの開始・再開でtoastのエラーが出る

Session launcherのStartやRestart sessionが拒否されると、右上にtoastが出る。

Session starting（Restart sessionではSession restarting）が出た場合は受け付けられている。その後に始まらないときはSessionが起動しないへ進む。

応答の終わりに状態badgeが付く

agentの応答が通常どおり終わらなかったとき、Session画面の応答の下に状態のbadgeが付く。押すと説明が開く。

続きを頼む前に、それまでのtool実行やファイル変更が残っているかを確認する。同じ依頼を最初から送り直すと、同じ作業が重なることがある。

Teamや参加リンクを開けない

• You don’t have access to this Team. — そのTeamのmemberでなく、参加しているProjectもない。TeamのOwner / Adminに招待を依頼する
• Invite link not found（The link may be invalid or has already been rotated.） — 参加リンクが無効か、作り直されて古いリンクが無効になった。リンクを読み込めなかった場合も同じ表示になる。一度再読み込みし、続くならリンクを発行した人に新しいリンクを依頼する
• You need to log in to join. — サインインしていない。表示内のLog inからサインインすると、同じ参加リンクへ戻る
• You are already a member — すでに参加している。Openで開く

Projectの参加リンクとrotateはProjects、Teamの招待はTeamsを参照する。

Team File Treeを接続・更新できない

Team SettingsのTeam File Treeに状態が出る。接続と更新はTeamのOwner / Adminが行う。

接続そのものが拒否される場合はGitHub repositoryを接続できないを参照する。Team File Treeは表示用で、agentが作業するrepositoryの設定とは別である（Connected Repository）。

添付を追加できない

添付できる形式と上限は容量・実行条件にある。WebUIでは次のtoastやカードの表示で止まる。

アップロード中は送信できない。カードがAttached to the timelineまたはUsed in this Session onlyになってから送る。

HTMLを開くとPopup blockedが出る

ProjectのHTMLは新しいタブで開く。ブラウザがポップアップを止めるとPopup blocked（Allow popups for aachat, then open the HTML again.）が出る。ブラウザのアドレスバーなどからaachatのポップアップを許可し、もう一度開く。

HTML needs index.htmlはHTTP 409共通のtitleであり、それだけでは原因を確定できない。直下のdescriptionを読む。Create ... index.html before opening project HTML.なら指定のindex.htmlを作る。Project HTML delivery build is not ready...ならProject HTMLが同期されない・表示が古いへ進み、最新build診断とMediaの状態を確認して原因を解消する。Failed to open HTMLの場合は再試行し、接続とProjectの権限を確認する。HTMLの同期や表示の古さも同じ復旧節を参照する。

Desktop app

macOSのaachat Desktopの初回準備・サインイン・ガイド・アプリ更新の不調。アプリの使い方はmacOS Desktopを参照する。

失敗すると、吹き出しに理由が出てもう一度が表示される。まず理由を読み、もう一度を押す。もう一度は、選んだランタイムを保ったまま状態確認と準備からやり直す。表示中の会話と未送信の確認は消える。過去の仕事や同意を再実行しない。

初回の準備で止まる

「会話に必要なソフトを準備しています」の間に、アプリはNode.jsと選んだランタイムの実行環境を専用フォルダへ用意する。Node.jsはnodejs.orgから、ランタイムはnpmのパッケージとして取得する。準備済みの部分は次回から再利用される。

社内ネットワークやプロキシの下では、nodejs.org、npmのregistry、aachat.io、選んだランタイムのサインイン先に接続できるか確認する。

ガイドに必要なファイルを取得できない

ガイドに必要なファイルを取得できませんでした。接続を確認して、もう一度試してください。は、ガイドの説明ファイルをaachat.ioから取得できず、前回取得した控えもない状態である。取得は30秒で打ち切られる。ネットワークを確認してもう一度を押す。一度取得できていれば、取得に失敗しても前回の控えで起動する。

サインインが完了しない・時間切れになる

「ブラウザでサインインしてください。終わったらここに戻ってきてください」の間に、ブラウザを開くで選んだサービスの認証を完了する。Codexではアプリに出た認証コードをブラウザで入力する。

ブラウザを開けたことだけではサインイン完了にならない。アプリが完了を確認してから会話が始まる。

ガイドへの接続が時間切れになる・ガイドが止まった

• ガイドへの接続が時間切れになりました — 準備したランタイムが、起動の各段階で2分以内に応答しなかった。もう一度を押す
• ガイドが止まりました。もう一度お試しください — 会話中にランタイムが止まった。もう一度で新しい会話から始める。止まる前の会話は引き継がれないので、必要な要点を書き直す
• ガイドの接続方式に対応していません — 準備したランタイムとアプリの組み合わせが合わない。アプリを最新版へ更新する
• 画面に操作を完了できませんでした。もう一度お試しください。や返事を送れませんでした。もう一度送ってください。が出た — その操作だけが失敗した。もう一度押す、または送り直す

同じ失敗が続く場合は、アプリのメニューのガイドをやり直すで初回画面に戻り、ランタイムを選び直す。もう一方のランタイム（Claude Code / Codex）を選ぶこともできる。

保存されたガイドの設定を読み取れない

保存されたガイドの設定を読み取れません。メニューからガイドをやり直してくださいは、前回選んだランタイム等の準備状態の記録が壊れている状態である。このときはもう一度では直らない。アプリのメニューからガイドをやり直すを選ぶ。

ガイドをやり直すは、ランタイムの選択と画面の会話・未送信の確認をリセットする。用意済みのNode.jsとランタイム、aachatの共通ルートと作業ファイル、ClaudeやCodexのサインイン情報は残る（macOS Desktop）。ガイドをやり直す準備ができませんでしたが出た場合は、アプリを終了して開き直してから再度選ぶ。

アプリを更新できない

アプリは起動時とDockから開き直したときに更新を確認し、準備できると「新しいバージョン」と更新して再起動を出す。

• アプリを更新できませんでした。 — 更新の確認・取得に失敗した。現在のアプリはそのまま使える。あとでで閉じ、Dockのアイコンから開き直すと再確認する
• アプリケーションからaachatを開き直してください。 — 更新後の再起動で、期待した版で起動しなかった。アプリケーションフォルダからaachatを開き直す
• 更新の操作を完了できませんでした。 — 更新して再起動やあとでの操作が失敗した。あとでが失敗した場合はもう一度押す。更新して再起動が失敗した後は、もう一度押しても適用されないので、アプリを終了して開き直すと再確認する

開き直しても直らない場合は、公式DesktopリリースページからDMGを取得し、Applicationsのaachatを置き換える。アプリの更新とaachat CLIの更新は別である。CLIはaachat updateで更新する（セットアップ）。

Desktopで解決しないとき

ガイドが起動しない、または同じ失敗が続く場合は、ターミナルでaachat supportを使う。aachat CLIと、Claude CodeまたはCodexのCLIが必要である。

aachat support

Codexを使う場合はaachat support --provider codexを使う。起動後に、Desktopの吹き出しに出た理由、時刻、選んだランタイム、アプリの版を伝える。ガイドのランタイムのエラー出力は~/Library/Application Support/work.aachat.desktop/guide/logs/runtime.logにあり、ガイドを起動するたびに上書きされる。上書きされる前に確認する。aachat CLIがまだ入っていない場合はCLIセットアップから始める。Desktopを終了しても、ガイドがCLIで起動したaachat runtimeは止まらないので、aachat statusで状態を確認できる。

Discoverのcloneが失敗する

WebのDiscoverからのclone： GitHubのrepoとworkflowの権限が必要である。足りない場合はrepositoryを作る前に止まり、Clone stopped before creating a GitHub repository because the <scope> permission is missing. Select Back to Discover, start the clone again, and re-authorize GitHub.が出る。Back to Discoverからcloneをやり直し、GitHubの認可で求められた権限を許可する。

CLIのaachat agent 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を実行する

Webhookが拒否される・起動しない

Triggerの状態、権限、secret設定、occurrence履歴を確認する。通信失敗時は同じ要求と冪等性キーで再送し、受付済みの仕事は返されたstatus URLから確認する（Triggers）。

supportで解決できないとき

起動済みのsupportとの対話を続ける。起動し直す必要はない。通常の入口は次のとおり。

aachat support

supportは検証できた修復と未解決事項を区別し、必要なら最小限の伏字済み報告を用意する。報告の受理は修復完了を意味しない。人間のサポート窓口はcontact@aachat.ioである。

関連ページ

• Sessionの仕様（状態遷移・記録・workspace・委任）はSessions
• 上限と入力単位は容量・実行条件
• agent repoの構造と反映タイミングはAgents
• secret・環境変数の仕組みはEnvironment
• エラーcodeの意味と次の操作はエラーコード索引
• コマンドの出力形式はCLI
• 用語の定義は用語集