Skip to content

fix: web-content-extraction の依存 lock 残留時に update が無言で終了コード 75 になる問題を修正(v0.79.1) - #179

Merged
okash1n merged 1 commit into
mainfrom
fix/update-wce-lock-stale-v2
Oct 7, 2026
Merged

okash1n merged 1 commit into
mainfrom
fix/update-wce-lock-stale-v2

Conversation

@okash1n

@okash1n okash1n commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

概要

/update-kit(setup.sh --update)が、web-content-extraction skill の依存 lock(~/.claude/skills/web-content-extraction/logs/.update.lock)が残っていると、Step 2/5 の直後に何も表示せず終了コード 75 で止まる問題を修正します(v0.79.1、patch)。

発見の経緯

この端末で /update-kit を実行したところ、Step 2/5(CLAUDE.md)の後に無言で終了しました。原因は 2026-09-06 から残っている lock で、owner のプロセス(依存 updater)は存在せず、以後 1 か月間、kit の更新と依存更新がすべて失敗していました(manifest は v0.77.1 のまま)。

原因

  • 依存 updater(update-deps.mjs)は lock を持ったまま同期の npm view を実行し、その間はシグナルハンドラが動かない。SessionStart の async hook として起動されるため、セッション終了時の強制終了で lock が残る
  • v0.73.0 で経過時間だけを根拠にした自動奪取を廃止して以降、残った lock を回収する経路がない
  • kit 側は lock 取得失敗時に何も表示せず exit 75 し、呼び出し元は errexit 下の単純コマンドなので無言で終了する
  • lock の取得は Step 2 の後なので、失敗のたびにバックアップ(この端末では約 1.2 GB)と settings.json / CLAUDE.md の書き換えが先に走り、snapshot / manifest だけが古い中途半端な状態になる
  • dry-run は一時ディレクトリで模擬するため検出できず、自動アップデートの失敗を利用者に知らせる経路もない

ユーザーに見える変更

  • 書き込み前に lock を確認: update ではバックアップの前、fresh では deploy の前に確認し、止まる場合は kit のファイルを一切変更しない。実行中の owner は最大 60 秒待つ
  • 止まった理由を表示: lock のパス、owner、作成時刻、owner の PID とその生存状態、状態別の復旧コマンド(日本語 / 英語)。終了コード 74(解放失敗)/ 75(取得失敗)の意味と、どこまで処理が進んだかの注記
  • owner のいない lock を自動回収: owner が kit の書く形式で、その PID のプロセスが存在せず、owner ファイルが 60 分以上前の場合に限る(MSYS / MDM では回収しない)。経過時間だけでの奪取は復活させていない
  • 依存 updater の lock 保持範囲を縮小: 最新版チェックの間は lock を持たず、更新を適用する間だけ取得する。中断マーカーがあれば 24 時間の throttle を迂回して復旧する
  • dry-run で警告: 実際の ~/.claude の lock を読み取りだけで確認し、自動回収されるか止まるかを表示する(rc は 0 のまま)
  • 回復後の CLAUDE.md: 失敗で中途半端になった環境の回復時、kit セクションが新 kit と同一なら利用者編集扱いにせず snapshot を更新する
  • 詳細は CHANGELOG の [0.79.1] を参照

変更内容(16 ファイル)

ファイル 変更
lib/update.sh lock の inspect / preflight / 自動回収(mutex → 再照合 → rename 隔離 → 再照合 → 削除)/ 診断表示。取得側は owner を noclobber で書き、reclaim mutex を見つけたら最大 3 秒待って token 照合付きで取り下げる。解放も同じ mutex で直列化し、token の PID は保持サブシェルの BASHPID。CLAUDE.md の snapshot 収束
setup.sh / lib/deploy.sh / lib/dryrun.sh preflight の呼び出し、終了コードの伝播、dry-run の警告
skills/web-content-extraction/scripts/update-deps.mjs チェック中は lock 非保持、取得後の canonical owner 再照合、マーカー優先の復旧
i18n/en / i18n/ja STR_WCE_LOCK_*
commands/update-kit.md / update-kit-dry-run.md / skill README / CLAUDE.md 終了コードと復旧手順、設計の説明
テスト tests/unit/test-wce-update-lock.sh +44、test-update-refactor.sh +2、skill の node テスト +15、シナリオ +3

リスク

  • 設計判断の変更: v0.73.0 の「既存 lock は常に拒否」から、「owner の不在を確認できる場合に限り回収」に変える。残るリスクは、PID 名前空間が異なる共有 HOME(コンテナ、WSL から Windows の node.exe)で生存 owner が不在に見える場合と、lock 保持プロセスだけが SIGKILL され子の npm ci(timeout なし)が 60 分を超えて動き続ける場合。どちらも 60 分条件で緩和し、CHANGELOG と skill README に記載
  • 回収中に SIGKILL されると reclaim mutex(.update.lock.reclaim)が残り、以後の自動回収は止まる(診断で mutex の削除手順を表示)
  • preflight 通過後から tail の lock 取得までの数秒に別 writer が lock を取る競合は残る(その場合は原因と「settings.json / CLAUDE.md は処理済み」が表示される)
  • Linux / WSL / MSYS(/proc 分岐、GNU stat / find -mmin、MSYS 判定)は macOS でのみ確認。CI の ubuntu で確認する
  • 自動アップデート失敗の SessionStart 通知は含まない(別件)

実行した検査

  • 実装 1 ラウンド + レビュー 8 ラウンド(正しさ / セキュリティ・競合 / テスト・文書 / Codex)で計 25 件の指摘を修正。最終ラウンドは競合観点・Codex ともに指摘なし
  • ミューテーション検査 13 種(回収条件、再照合、mutex、MSYS / MDM ガードなど)をすべてテストが検出。並行回収ストレス(120 ラウンド × 8 並列、80 × 12)で失敗 0
  • 詰まった実環境の状態を使い捨て HOME で再現し、setup.sh --update --non-interactive が rc=0 で lock を回収し、snapshot / manifest が更新されることを確認
  • 通常環境(lock なし)で main と出力を比較: 差分は追加したテストファイル分のみ
  • shellcheck -S warning(変更 .sh)、git diff --check、node --check
  • tests/unit/test-wce-update-lock.sh(65 件)、test-update-refactor.sh、skill の npm test(63 件): 全件 PASS(最終レビュー時点)。積み直し後の再実行は PR 作成と並行して実施中
  • 全体スイートはローカル未実行。CI を正とする。この端末の実 lock に対する動作は、マージ後に /update-kit で確認する

…正(v0.79.1)

install.sh / /update-kit / 自動アップデートが呼ぶ setup.sh --update は、
Step 2/5(CLAUDE.md)の後で web-content-extraction の依存 lock
(~/.claude/skills/web-content-extraction/logs/.update.lock)を取得する。
依存 updater(update-deps.mjs)が lock を持ったまま強制終了されると lock が
残り、以後の update は何も表示せず終了コード 75 で止まっていた。しかも
backup と settings.json / CLAUDE.md の書き換えは lock 取得より前に走るため、
失敗のたびに snapshot / manifest だけが古い中途半端な状態と 1 回分の
バックアップが残っていた。dry-run は一時ディレクトリで模擬するため検出
できず、自動アップデートの失敗を利用者に知らせる経路もなかった。

- setup.sh: update ではバックアップの前、fresh では deploy の前に lock を
  preflight する。実行中の owner は最大 60 秒待ち、止まるときは kit の
  ファイルを変更しない
- lib/update.sh: lock を取得・解放できないときにパス / owner / 作成時刻 /
  owner PID とその生存状態 / 状態別の復旧手順を表示する。owner が kit の
  書く形式で、その PID が存在せず、owner ファイルが 60 分以上前の lock に
  限り、reclaim mutex の下で再照合 → rename で隔離 → 再照合 → 削除する
  手順で自動回収する(MSYS / MDM では回収しない)。取得側は owner を
  noclobber で書き、mutex を見つけたら最大 3 秒待って token 照合付きで
  取り下げる。解放も同じ mutex で直列化し、lock token の PID は保持
  サブシェルの BASHPID を記録する
- lib/update.sh: 失敗で中途半端になった環境の回復時、CLAUDE.md の kit
  セクションが新 kit と同一なら利用者編集扱いにせず snapshot を更新する
- update-deps.mjs: 最新版チェックの間は lock を持たず、更新を適用する間
  だけ取得して installed version を読み直す。中断マーカーがあれば 24 時間
  の throttle を迂回して復旧する。取得後に canonical owner を再照合する
- lib/dryrun.sh / setup.sh: dry-run は実 ~/.claude の lock を読み取りだけで
  検査し、自動回収されるか止まるかを警告する
- i18n: STR_WCE_LOCK_* を en / ja に追加
- 文書: commands/update-kit.md / update-kit-dry-run.md に終了コード 75 / 74
  の意味と復旧手順、skill README に lock の設計、CLAUDE.md に preflight と
  回収の規約を追記
- テスト: tests/unit/test-wce-update-lock.sh に 44 件、test-update-refactor.sh
  に 2 件、skill の node テストに 15 件、シナリオ 3 件を追加

v0.73.0 で廃止した「経過時間だけを根拠にした stale lock の自動奪取」は
復活させていない。回収は owner プロセスの不在を確認できる場合に限る。
自動アップデート失敗の SessionStart 通知は含まない。

レビュー 8 ラウンド(正しさ / セキュリティ・競合 / テスト・文書 / Codex)
で計 25 件の指摘を修正し、最終ラウンドは指摘なし。
Copilot AI balanced review requested due to automatic review settings October 7, 2026 00:49
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-07T00:54:23.493689Z 50535ac PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Lock-release diagnostics can announce exit 74 while the wrapper returns the callback’s different failure status.

Review effort: Balanced
Findings: 1 Medium severity · 1 Low severity

Open (2)
What changed in this PR

Fixes silent update failures caused by stale web-content-extraction dependency locks.

Changes:

  • Adds preflight lock diagnosis, waiting, and bounded stale-lock recovery.
  • Narrows updater locking to mutation phases and improves interrupted-update recovery.
  • Adds localization, recovery documentation, snapshot convergence, and regression tests.
File Description
lib/​update.sh Implements lock recovery, diagnostics, and snapshot convergence.
setup.sh Runs preflight before deployment writes.
lib/​deploy.sh Propagates lock-specific exit codes.
skills/​web-content-extraction/​scripts/​update-deps.mjs Narrows lock scope and handles interrupted updates.
skills/​web-content-extraction/​test/​update-deps-run.test.mjs Tests updater execution and lock scope.
skills/​web-content-extraction/​test/​update-deps-lock.test.mjs Tests lock/reclaimer races.
skills/​web-content-extraction/​README.md Documents lock behavior and recovery.
tests/​unit/​test-wce-update-lock.sh Adds extensive lock regression coverage.
tests/​unit/​test-update-refactor.sh Tests CLAUDE.md baseline refresh.
tests/​run-scenarios.sh Adds end-to-end lock scenarios.
i18n/​en/​strings.sh Adds English diagnostics.
i18n/​ja/​strings.sh Adds Japanese diagnostics.
commands/​update-kit.md Documents exit codes and recovery.
commands/​update-kit-dry-run.md Documents dry-run lock warnings.
CLAUDE.md Records lock architecture constraints.
CHANGELOG.md Adds the v0.79.1 release notes.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread lib/update.sh
[[ "$release_rc" -eq 0 ]] || release_rc=74
if [[ "$release_rc" -ne 0 ]]; then
release_rc=74
_wce_runtime_update_lock_report "$current_dir" 74 || true
Comment thread lib/update.sh
# baseline (for example on the dependency lock after Step 2). That is not
# a user edit. Leave the file as it is and let the caller refresh the
# snapshot so the next update compares against the right baseline.
return 3
@okash1n
okash1n merged commit f00e7ce into main Oct 7, 2026
14 checks passed
@okash1n
okash1n deleted the fix/update-wce-lock-stale-v2 branch October 7, 2026 03:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants