山村商店

agmsg Windows 高速化レイヤー(accel) 解説書

目次
  1. 1. これは何か
  2. 2. インストールと運用
  3. 3. 仕組み
  4. 4. 同梱ファイル(sources/・全15件・md5で正本一致確認済み)
  5. 5. 障害時の手がかり
  6. 6. 配置先の対応(実処理の正本=`~/.agents`側。本パッケージは配布物)
  7. 7. 更新履歴・歴史資料・上流関連(参考)

(配布ファイル「accel.zip」は現在提供していません)

パッケージ版数: v1.0(2026-08-03)/ 種別: 解説・配布用パッケージ
対象: agmsg(bash製エージェントメッセージング基盤)を Windows/MSYS(Git Bash)環境で
実用速度にする外部レイヤー。実際に処理へ使われている正本は `~/.agents/` 側(対応表は§6)。
本パッケージはその解説書+配布用完全セット(sources/ 15件+install.sh)で、これだけで
別環境へ導入できる。導入方法は§2、実装を修正した時は本パッケージへ反映して版数を上げ
§7へ履歴を書く。上流(agmsg本体)は原則無改変(唯一の例外は§7.4)。

1. これは何か

1.1 問題: agmsgはWindowsで桁違いに遅い

agmsgは純bashで書かれ、`tr`/`sed`/`stat`/`uname`等の外部コマンドを1セッション起動
あたり数百回呼ぶ。Linuxでは問題にならないが、Windows/MSYSでは:

| 要因 | 実測 |
|---|---|
| MSYSのfork | 約47-68ms/回(Linuxの30-50倍) |
| 外部exe実行(exec) | 約200-500ms/回 ← 主犯 |
| クラウド同期ドライブ上の作業ディレクトリのI/O | stat 20倍・read 76倍・列挙 17倍(ローカルSSD比) |

1回200-500ms×数百回=分単位の遅延。コードの問題ではなくMSYSの構造コスト。

1.2 解: 上流無改変の外部レイヤー

bashは非対話スクリプト実行前に環境変数 `BASH_ENV` が指すファイルを読む。
そこでシェル関数を定義すると、関数は外部コマンドより優先解決されるため、
上流スクリプトを1行も書き換えずに `sed` 等の呼び出しを純bash実装へ差し替えられる。

設計原則:

  1. 上流ファイルを書き換えない(全ロジックは `~/.agents/agmsg-local/` に置く)

  2. スコープ限定注入: BASH_ENVは自前ランチャだけがexportする。通常のGit Bashには無影響

  3. byte-exact fast-path: 実測で観測した呼び出し形(引数の完全一致)だけを純bashで受け、
    それ以外は `command <tool> "$@"` で必ず本物へフォールバック

  4. fail-open: レイヤーのどこが壊れても純正動作へ戻るだけ。起動をブロックしない

  5. probe gate: 上流やレイヤー自身が更新されたら、回帰テスト合格まで自動で無効化

1.3 効果(実測・一例)

| 対象 | 前 | 後 |
|---|---|---|
| セッション起動処理(session-start) | 258.5秒 | 119.5秒 |
| whoami(席の身元確認) | 5-20秒 | キャッシュHIT 0.3-2秒 |

主寄与: `uname -s`(298回/起動)のファイルキャッシュ化、rollout `stat`(142回)の一括表化。

2. インストールと運用

2.1 前提条件

| 必要物 | 確認方法 | 備考 |
|---|---|---|
| Windows + Git for Windows(Git Bash) | `bash --version` | MSYS環境 |
| python3(Git Bash内) | `python3 -V` | stat一括表の生成に使用 |
| agmsg本体 | `~/.agents/skills/agmsg/` が存在 | 本パッケージはagmsg本体を含まない |

2.2 インストール手順

# 1. 本パッケージのディレクトリで(差分確認→配置→md5検証まで自動)
bash install.sh            # 確認だけなら: bash install.sh --check

# 2. probe(回帰テスト)を実行 — 合格するまでfast-pathは有効化されない
cd <プロジェクト>
AGMSG_PROBE_PROJECT="<プロジェクトパス>" AGMSG_PROBE_TYPE=codex \
  bash ~/.agents/agmsg-local/accel/accel-probe.sh --fast

# 3. ランチャ側の注入(§2.3)を確認して完了

2.3 BASH_ENVの注入(ランチャ側の1行)

高速化は「BASH_ENVを注入されたプロセスチェーン」でだけ効く。自前ランチャの先頭で:

export BASH_ENV="$HOME/.agents/agmsg-local/accel/agmsg-env.sh"

を行ってから対象(例: codexのTUI)を起動する。グローバル(~/.bashrc全体)には設定しない
(通常のシェル作業へ影響させないための設計)。

2.4 運用ルール(これだけ守れば壊れない)

  1. accel系ファイルを編集したら probe を再実行(しないとgateが閉じ純正速度に戻る=遅いが安全)

  2. fast-pathを追加したら回帰ケースも追加(accel-regression.sh)

  3. 不調時は `AGMSG_ACCEL_DIAG=<ファイル>` でhit/fallbackを記録して切り分け。
    全fallbackならgate閉を疑う(→probe再実行)

  4. agmsg本体を更新したら `reapply.sh` → probe

  5. `.enabled` を手でtouchしない(未検証の加速を開けることになる)

3. 仕組み

3.1 注入と gate

`agmsg-env.sh`(BASH_ENVエントリ)は、`.enabled` マーカーが監視対象すべて
(上流 `whoami.sh`/`identities.sh`/`lib/*.sh` + 自層 `agmsg-accel.sh`/
`agmsg-accel-lastpipe.sh`/`identities-intercept.sh`/`agmsg-env.sh`)より新しい時だけ
fast-path群をsourceする。1つでも新しいファイルがあれば何もsourceしない=純正動作。
`.enabled` は probe(回帰テスト)合格時にのみ更新される。
**「検証していない加速は絶対に走らせない」**がこの仕組みの核。

3.2 fast-path(agmsg-accel.sh)

観測済み呼び出し形だけを受ける関数群: `tr` `sed` `dirname` `cygpath` `uname` `cat`
`cut` `paste` `grep` `awk` `head` `wc` `stat`。代表例:

  • uname -s: ファイルキャッシュ(2列: `<MSYSTEM>\t<値>`)。鮮度=uname実体のmtime比較+
    MSYSTEM世代一致。検証とパースは関数内に一本化(事前のenv投入は禁止 — §7.2の教訓)

  • stat -c %Y(セッション記録ファイル): 同形の問い合わせ多数をpython3一括で表に落とし、
    以後fork0のreadループで即答。対象が表より新しい/存在しない場合は実statへ(古い値を返さない)

  • sed(ポート抽出等): 引数列が完全一致し、対象が「通常ファイルかつ可読」の時だけ純bash。
    それ以外は実sedへ(終了コードまで一致させる)

診断: `AGMSG_ACCEL_DIAG=<file>` で hit/fallback を1行ずつ記録(未設定時はコスト0)。

3.3 キャッシュとラッパ

  • `identities-intercept.sh`: 上流 `identities.sh` の実行結果を引数キーでキャッシュ

  • `wrappers/whoami-cached.sh`: `whoami.sh`(60+サブプロセス・5-20秒)のファイルキャッシュ版。
    agmsgツリーへも同名で配置され、既存の呼び出しパスから使える

  • `warm-caches.sh`: チーム参加後、全登録ペアのキャッシュを背景で予熱(stale分のみ。
    ランチャ側から遅延起動して起動直後の競合を避ける運用)

  • lastpipe変種(`agmsg-accel-lastpipe.sh`)はパイプ末尾のfork1回を節約するが、
    `| while read` の意味を変えるため whoami-cached 内部だけで使用(BASH_ENVには含めない)

3.4 回帰スイート(accel-regression.sh)

fast-path出力と本物の出力・終了コードの完全一致を検証(2026-08-03時点69ケース)。
probe(`accel-probe.sh`)がこれを実行し、合格時のみ `.enabled` 更新+値キャッシュ無効化。

3.5 再適用(reapply.sh)

agmsg本体の更新はツリー側の配置物(whoami-cached等)を消すことがある。`reapply.sh` は
ローカル適応を冪等に再適用する(パッチは3-wayマージ。§7.4の上流パッチは、修正済み
上流版を検出したら自動で適用をやめる)。

4. 同梱ファイル(sources/・全15件・md5で正本一致確認済み)

| ディレクトリ | ファイル | 役割 |
|---|---|---|
| sources/accel/ | agmsg-env.sh | BASH_ENVエントリ+gate(§3.1) |
| | agmsg-accel.sh | fast-path関数本体(§3.2) |
| | agmsg-accel-lastpipe.sh | lastpipe変種(限定用途・§3.3) |
| | identities-intercept.sh | identitiesキャッシュ |
| | accel-probe.sh | 回帰probe=gateの鍵(§3.4) |
| | accel-regression.sh | 回帰スイート69ケース |
| | warm-caches.sh | キャッシュ背景予熱(実体) |
| | README.md / AUTHOR_FYI.md | レイヤー内README/上流作者向け説明(§7.4) |
| sources/wrappers/ | whoami-cached.sh | whoamiキャッシュ(実体) |
| | warm-caches.sh | 旧パス互換の橋(forwarder) |
| sources/patches/ | instance-id.base.sh / .ours.sh | 上流パッチの3-wayマージ用(§7.4) |
| sources/local-root/ | reapply.sh | agmsg更新後の再適用(§3.5) |
| sources/agmsg-tree/ | whoami-cached.sh | ツリー側配置コピー(実体と同一内容) |

5. 障害時の手がかり

  • fast-pathが効いていない気がする → `AGMSG_ACCEL_DIAG` で確認。全fallbackなら
    gate閉(→probe再実行)。`.enabled` と各ファイルのmtime比較でも判定可能

  • probe不合格 → 出力されたFAILケースを見る。上流の呼び出し形が変わった可能性が
    高い(その場合fast-path側を追従させ、回帰ケースも更新)

  • キャッシュの値が怪しい → probe再実行(合格時に値キャッシュは自動無効化される)。
    手動なら `.uname-s.cache` `.rollout-mtimes` を削除(次回アクセスで再生成)

6. 配置先の対応(実処理の正本=`~/.agents`側。本パッケージは配布物)

| パッケージ(sources/) | 配置先(=実際に処理へ使われる正本) |
|---|---|
| sources/accel/* | `~/.agents/agmsg-local/accel/` |
| sources/wrappers/* | `~/.agents/agmsg-local/wrappers/` |
| sources/patches/* | `~/.agents/agmsg-local/patches/` |
| sources/local-root/* | `~/.agents/agmsg-local/` |
| sources/agmsg-tree/* | `~/.agents/skills/agmsg/scripts/` |

`install.sh` はこの表のとおりに配置する。実装を修正した時は、正本側での動作確認
(probe合格)後に本パッケージのsources/へコピーし直し、版数を上げて§7に履歴を書く。
姉妹パッケージ: antigravity統合 = `../antigravity/`

7. 更新履歴・歴史資料・上流関連(参考)

7.1 開発の経緯

  1. 「agmsgが異常に遅い」調査から開始。プロファイルの結果、外部コマンドのexecコストが
    支配的と判明(fork/exec分解計測)。クラウド同期ドライブのI/O遅延も副因

  2. WSL2移行・作業ディレクトリのローカル移動はいずれも運用上の理由で不採用とし、
    「Windows + Git Bash + agmsg標準bash」のまま詰める方針を確定

  3. BASH_ENV注入方式を段階導入(観測→inventory→fast-path→probe gate→回帰スイート)

  4. 2026-08-02〜03: 外部レビュー(正しさレンズ)でP1級の欠陥を複数検出・修正(§7.2)

7.2 主要な欠陥と教訓(再発防止の根拠)

| 事象 | 教訓 |
|---|---|
| statのfast-pathを3回作り損ねた(subshellで変数消失/パス正規化差/鮮度チェック自体が2 fork) | fast-pathはfork数を数えて設計し、diagで実測確認 |
| sedのfast-pathを誤った引数数で書き、一度も発火していなかった | 性能改善の寄与分析を怠らない。回帰は実呼び出し形で書く |
| キャッシュを2列化した際、別の読み手を更新し忘れ生行注入で検証迂回 | 形式変更は読み手全員を追従。パースは1箇所へ一本化 |
| gateが一部の注入経路に無く、上流更新後も未検証の加速が生き残った | gateは全注入経路に置く |
| 自動記録の新旧判定をmtimeで行い誤束縛の余地があった | 判定は集合差分(スナップショット)で。曖昧なら不作為に倒す |

7.3 版数履歴

  • v1.0(2026-08-03): 初版。fast-path 13コマンド・回帰69ケース・probe gate・
    whoami/identitiesキャッシュ・warm予熱・reapply。実測: セッション起動 258.5→119.5秒

7.4 上流(agmsg作者)との関係

  • 高速化はすべて外部レイヤーで実施し、上流ファイルの書き換えは1件を除きゼロ

  • 唯一の例外 = `scripts/lib/instance-id.sh` の1関数パッチ: プロセス生存確認が
    MSYSのpid空間とWindowsのpid空間を混同するバグ(監視系が恒常的に「死んでいる」と
    誤判定)への対処。上流へ報告済みで本家に修正が入っており、修正入りの上流版を
    `reapply.sh` が検出したら自動で適用をやめる    (自然消滅する設計)

  • Windows環境の性能特性(fork/execコスト・呼び出し回数の実測)も上流へ報告済み。
    `sources/accel/AUTHOR_FYI.md` は上流作者向けにレイヤーの仕組みと計測をまとめたもの

【宣伝】SwitchBot 購入はこちらから

SwitchBot公式ページ
クーポン「AF-4903」で5％引き（アフィリエイトクーポンになりますのでご協力お願いします）
割引の詳しい仕組みに関してはこちらのページを参照ください。
製品ごとの特徴・紹介動画は SwitchBot 製品ガイド にまとめています。

その他おすすめリンク

【2026年8月】クーポン・ポイント情報　GMKtec MINISFORUM GEEKOM ACEMAGIC　公式サイト攻略法

How to Get the Lowest Price on the SwitchBot Official Store (US, UK & EU): The Complete Checkout Strategy — August 2026

当ページにはアフィリエイトリンクを含む場合があります。

その他おすすめリンク

【2026年8月】クーポン・ポイント情報　GMKtec MINISFORUM GEEKOM ACEMAGIC　公式サイト攻略法

How to Get the Lowest Price on the SwitchBot Official Store (US, UK & EU): The Complete Checkout Strategy — August 2026

当ページにはアフィリエイトリンクを含む場合があります。