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

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

症状から復旧手順を選ぶ

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

まずchat --versionとchat media --helpでdownload対応を確認します。未対応なら止め、対応版を確認してください。media_unavailableなら同Projectのready一覧と対象・準備状況を確認します。media_download_failedならreasonを読んで一度再試行し、再失敗をchat reportへ報告します。成功JSONなしに内容を推測したり、残っている同名ファイルを今回の取得成功としたりしません。APIの認証・権限エラーも取得失敗と分けて確認します。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）。help/versionはtextです。結果が不明な書込や起動は、既存の受付・対象状態を確認してから操作別の再送手順に従います。診断を増やす目的で同じ操作を重ねないでください。

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

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

Sessionログの手順で読むstderrと、常駐runtimeの診断logは別です。server側の既存stdoutや設定されたruntime logが必要なら、権限のある管理者/supportへ上記の時刻・IDを渡して照合を依頼します。閲覧不能は空ログではなく未確認であり、全ログの保存や保持期間を保証しません。HTTP相関とredirectで止まった場合は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の手順はセットアップ、詳細条件は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）。パネルがないだけで未登録としない。
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の状態を確認する。変更後の回答が必ず自動送信されるとは限らない（回答保存と継続）。

取消はsettledでも承認ではなく、後の回答変更も同じwaitを再発火しない。通知の意味と対応版の条件はSessions、回答条件は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、受け入れはProjectsを参照する。

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

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

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

1. projectのPROJECT.md — 安定したPurpose、Outcome、Outputs、判断原則・境界、curated Context Map、Approachが書かれているか。無い、またはこの安定契約が古い場合は整備する。進捗・担当・handoff・ログ・未解決メモ・task blockで更新しない
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）
4. agent repoのmemory — project横断で持ち回るべき経験則・知識がagent repoの memory/ にあるか。無ければ書いてpushする。反映は次のsessionからである

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

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

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

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

対処: 変更をpushし、新しいsessionを起動する。agent repoの構造は 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）

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を参照する。

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）。

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

1. 元Sessionを開き、受付turnと保存済みtranscriptを読みます。startingなら回復中の可能性があるため、run/sendを重ねず次の状態・応答を確認します。
2. 成果文書、working tree、push・PR等のdeliveryと外部操作の結果を確認し、既に実行された仕事を切り分けます。受付済みの仕事は条件付きで再配送されるため、外部操作が一度だけとは限りません（回復条件）。
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は読取失敗です。検索範囲と抜粋の限界を確認してください。

ログを見たい

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

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

認証で失敗する

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

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に記録される。

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

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

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行を確認する。

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 を参照する。

Shared Documentsが同期されない

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

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 稼働中のみ行われる（信頼境界）。

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またはmaskする場合がある。

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のaachat / aachat-asksはrepo-nativeの予約surfaceで、runtime discoveryから意図的にmaskされる
5. workspace / TeamとAgentに同じ非Platform名のskillがある場合、workspace側が意図的にshadowする。意図しないならどちらかをrenameする
6. symlink、directoryだけのskill、特殊file、不正なfile名を通常のUTF-8 fileへ置き換え、commit / pushして新しいsessionを起動する

正本とprecedenceは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。

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

source sync後のserving snapshot rebuildが失敗すると、以前の正常snapshotが表示され続ける。HTML catalogのrebuild statusとerrorを確認し、原因fileを直してrebuildする。aachat upのsync状態だけを見て「表示更新済み」と判断しない（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）。

project削除が失敗した

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

それでも解決しないとき

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

aachat support

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

関連ページ

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