feat(api): add lossless forward message pagination

[ethfumi]

背景

docs/building-on-agmsg.md は、agmsg の外側から読むコードに対して「ファイルではなくスクリプトを通すこと」を求めています。ストアは実装詳細であって契約ではなく、messages.db を直接開くコードは storage 軸が入れば警告なく壊れる、と明示されています。GUI アプリ・ダッシュボード・他言語の bot・派生プロジェクトは api.sh を使うことになります。

その api.sh に、新着を取りこぼさずに追う手段がありません。team messages は最新行から後ろ向きにしか辿れないため、api.sh に従うクライアントは「最新 N 件」を取り直して差分を取るしかなく、2回の polling の間に N 件を超えて届いた分を静かに失います。

一方、DB を直接開くコードは WHERE id > <cursor> ORDER BY id で正しく追えます。前回から何行増えていても取りこぼしません。

つまり、ドキュメントが推奨する側のクライアントだけが、取りこぼしのない polling を持っていない状態でした。この差を埋めます。

この必要性は、別マシンの DB を SSH 経由で読む機能を作る中で顕在化しました。remote は api.sh 経由でしか触れないため、ローカルなら当たり前に使えるカーソルが、そこだけ使えませんでした。ただし問題自体は SSH に固有ではなく、api.sh を使うすべてのクライアントに共通です。

変更内容

カーソルより後ろの行だけを取得する --after-id を追加しました。forward のページングは、昇順で返す前に「条件に合う最も古い行」から選ぶため、クライアントがどれだけ遅れていてもカーソルを進めるだけで行を飛ばしません。後ろ向きの履歴取得は従来の最新ページ方式のままです。

--before-id と --after-id の同時指定は、どちらかを暗黙に優先せずエラーにします。

検証

tests/test_api.bats に、カーソルの排他性と、複数ページにまたがる forward の順序を追加しました。