RUNBOOK

トラブル対応

症状から現在のstateと失敗境界を特定し、保存されたjobを壊さずに復旧します。

このページの内容

症状ではなく再開点・process・journal・worktreeを順に判断する手順は再開と状態照合にまとめています。

最初の3コマンド

環境、全体の運用カテゴリ、対象jobの詳細という順に絞り込みます。すべてmain checkoutから実行し、対象はJob IDで固定します。

新しいrunで上書きしない

jobのstateとworktreeは復旧の材料です。止まったslugへ再度runする前に、job showで状態を確認し、可能ならjob resumeを使います。

terminal

npx specrunner doctor
npx specrunner job ls --all --json
npx specrunner job show <job-id>

1doctor

runtime・config・auth・repo・storage

2job ls

running・対応待ち・archive待ち

3job show

status・step・branch・log

状態別の復旧

running 実行中のまま進まない

job lsのstale表示だけでresumeしません。sidecarのPID、同hostのprocess、別machine・CI・schedulerのactive runを確認します。process生存中はresumeできません。

terminal

cat .specrunner/local/<slug>/liveness.json
ps -p <pid> -o pid=,ppid=,etime=,command=

sidecar不在時、job lsは15分fallbackを使いますが、resumeはmissing sidecarを即staleとして扱い得ます。判断順は再開と状態照合を参照してください。

awaiting-resume 人間の判断を待っている

job showで停止stepとlog pathを確認し、実行時に出力されたreasonやlogから、曖昧なrequest、timeout、iteration枯渇、main checkout driftなどの原因を先に解消します。

terminal

npx specrunner job show <job-id>
# 全ゲート確認後
npx specrunner job resume my-feature

記録済みstepの直近3 outcomeがescalationまたはerrorの場合はresume safetyが停止します。--forceは原因を理解して変更した後だけ使います。

failed / terminated Pipelineが失敗・停止した

失敗したstep、error、log pathを確認します。network・権限・verificationなど外部原因を修正した後、同じslugをresumeします。

terminal

npx specrunner job show <job-id>
# /recovery の全ゲート確認後
npx specrunner job resume my-feature

archived / canceled resumeできない

この2状態は終了済みです。既存jobを再開せず、新しい変更として別slugのrequestを作成します。

「inside a worktree」で拒否される

view・resumeなどの運用コマンドは、agentが作業しているSpecRunner worktree内から実行できません。errorに表示されたmain checkout pathへ移動します。

terminal

cd <main-checkout-path>
npx specrunner job show <job-id>

理由。 agentが編集したworktree内のconfigを、運用判断へ混入させないためのguardです。

merge・archiveで止まる

検出状態	境界	対応
PR番号なし	archive開始前	`job show`でpr-create完了を確認
protected path / file list不完全	merge前	PRを人が確認。必要ならmanual merge後に同じcommandを再実行
checks pending / timeout	merge前	checks完了後に同じarchive commandを再実行
checks failed	merge前	失敗checkを修正し、PR head更新後に再実行
merge conflict	merge前	feature branchをbaseへrebaseし、`--force-with-lease`でpush
checks success + BLOCKED	merge前	required reviewなどbranch protectionを満たす
GitHub API error	merge前	token・権限・API状態を確認して再実行
postMergeVerify失敗	merge済み・cleanup前	base branchを修正。自動rollbackされない
cleanup warning	merge・state更新後	`git worktree list`とbranchを確認し、残骸だけ整理

terminal

# 同じslugの非終端jobが意図した1件だけか確認
npx specrunner job ls --all --json
npx specrunner job show <job-id>
npx specrunner job archive --with-merge my-feature
# cleanup後はslugで表示し、出力されたJob IDを固定値と照合
npx specrunner job show my-feature

同じslugの非終端jobが複数ある、または一覧のJob IDが固定値と違う場合は再実行しません。archive処理は再実行を前提に設計されています。正常時の全順序とmanual mergeの境界はPR・merge・archiveを参照してください。

storage診断に問題が出る

warn orphan worktree

対応する非終端job stateがないworktreeです。まずdry-runで対象を確認し、未commit・未pushの変更がないことを確認してから削除します。

terminal

npx specrunner job prune
npx specrunner job prune --force

未commitまたは未pushのworktreeは--forceでもskipされます。

fail journal integrity

events.jsonlはappend-onlyの一次情報です。復元前に現物をrepository外のincident directoryへcopyし、hashとGit historyを保存します。

terminal

mkdir -p <incident-dir>
cp <change-dir>/events.jsonl <incident-dir>/events.jsonl.corrupt
shasum -a 256 <incident-dir>/events.jsonl.corrupt
git log --oneline -- <repo-relative-events-path>
git show <candidate-ref>:<repo-relative-events-path> > <incident-dir>/events.candidate.jsonl

候補を生成したら、再開と状態照合の復元前validatorで全行とcounterを検査します。PASS candidate journalを確認できた場合だけ復元し、検証不能ならSTOPして保全物をmaintainerへ渡します。

terminal

# /recovery#integrity のcandidate validatorがPASSした後だけ
git restore --source=<verified-good-ref> -- <repo-relative-events-path>
npx specrunner doctor
npx specrunner job show <job-id>

validator、最後のtransition確認、PASS/STOP基準は再開と状態照合を正とします。

processが無言で終了する

Pipeline diagnosticを有効にし、最後に出たboundary logを確認します。stateが保存されていても、再開ゲートを省略しません。

terminal

npx specrunner job show <job-id>
# /recovery の全ゲート確認後
SPECRUNNER_DEBUG=pipeline npx specrunner job resume my-feature

記録するもの。 問題を特定できない場合も、job showのStatus・Step・Logと、最後のdiagnostic boundaryをセットで記録します。

参照ソース 7件

src/core/job-list/operations-view.ts状態と次の操作 src/core/resume/safety.tsstale・resume safety src/errors.tsworktree guardとhint src/core/archive/merge-then-archive.tsarchive failure分類 src/core/doctor/checks/storage/journal-integrity.tsjournal integrity src/core/doctor/checks/storage/orphan-worktrees.tsorphan worktree README.mddiagnostic logging