agent-session-batch-export

エージェントセッションを軌跡の素材としてキュレーションする

大量の claude_code / codex トランスクリプトを、エージェントが分析できる、未変更であることが証明可能な小規模コーパスにまとめます。

scripts/curate-sessions.sh — インデックスも、デーモンも、ネットワークも不要です。python3 はスキルの前提条件であり、特定の分岐だけに必要なものではありません。選別エンジンは scripts/funnel.py であり、これを使わずにコーパスを作成するサポート対象の経路はありません。

中核となる特性は、保持されるファイルが元のファイルとバイト単位で同一のコピーであることです。それぞれの SHA-256 が記録されます。再レンダリング、要約、変換は一切行わないため、後続の分析では情報が失われた表示ではなく、実際の軌跡（すべてのツール呼び出しと結果）を読み取れます。

パイプライン

Windows では scripts\pick-sessions.ps1 / scripts\curate-sessions.ps1 を使用してください（引数は同じです）。その理由については「操作方法」を参照してください。以下の .sh の例は Linux/WSL/macOS での表記です。

好みではなく、ターミナルを使えるかどうかでエントリーポイントを選んでください。

対話型シェル（あなたまたはユーザーがターミナルを見られる場合）。 1 つのコマンドでパイプライン全体を実行し、必要に応じてターミナルを起動して、ピッカーを開きます。

bash scripts/pick-sessions.sh -o ./cur --agent codex --min-lines 20

エージェント／ヘッドレス／CI（表示されるターミナルがない場合）。 エントリーポイントを繰り返し実行してはいけません。4 つのステージを実行してください。エントリーポイントが内部で呼び出す処理であり、ステージごとの実行も正式にサポートされています（同じコードを使用します）。

C=scripts/curate-sessions.sh

# 1. scan — enumerate candidates -> OUT/candidates.tsv
bash $C scan -o /tmp/cur --workspace cits4012 --min-lines 20

# 2. screen — YOU read the candidates and annotate them (see Screening)
#
# 3. review --ui tsv — emit decisions.tsv (no TUI, never blocks)
bash $C review --ui tsv -o /tmp/cur

# 4. THE USER edits decisions.tsv: set decision=keep|drop per row.
#    STOP here and run the Hand-off gate first — never fill the
#    decision column yourself.
#
# 5. finalize — ONLY after user approval (gate step 3), as their delegate:
#    materialize -> OUT/keep/*.jsonl + OUT/manifest.json
bash $C finalize -o /tmp/cur

ユーザーはターミナルを開けるが、エージェントは開けない場合（デスクトップ環境のない純粋な Linux）：ステージ 2 の後にワンクリックランチャーを生成してユーザーに渡してください。この環境では、それが対話型レビューとなります。

bash $C package -o /tmp/cur
# -> /tmp/cur/open-review.sh
# tell the user: open a terminal in /tmp/cur and run `bash open-review.sh`

ランチャーは選別済み候補の fzf ピッカーを開き、ユーザーが確定すると、同じ実行内でコーパスの最終処理と検証を行います。これで 1 回の操作は完了です。エージェントがスキャンと選別を行い、ユーザーが保持／除外を決めます。

ヘッドレス環境からエントリーポイントを実行した場合、対話型であるかのように装うことはありません。同じステージごとの実行手順を実際のパスとともに表示し、ゼロ以外の終了コードで終了します。

各ステージには完了条件が 1 つずつあります。

ステージ	完了条件
scan	candidates.tsv に、メタデータフィルターを通過したセッションごとに 1 行ある
screen	すべての行に suggested（keep／drop）と 1 行の reason が記載されている
review	decisions.tsv のすべての行に decision が記載されている
finalize	ユーザーが保持／除外リストを承認している（引き渡しゲート）。manifest.json に保持されたすべてのセッションが記載され、各 kept_as が対応する source と一致する

事前フィルター：candidates.tsv がすでにファネルを通過した候補である場合があります

決定論的な事前フィルターが、scan の後、あなたが作業する前に実行されている場合があります。その場合、フィルターを通過した候補が candidates.tsv となり、完全なスキャン結果は隣の candidates.full.tsv に保存されています。また、screen.tsv はその行だけを対象に再構築され、スクリーニングの段階で入力するため、suggested／reason 列は空のままです。ファネルの推奨は行セットそのものです。フィルターを通過した候補は、ファネルが注目に値すると判断したセッションであり、それらをスクリーニングするのは引き続きあなたの作業です。keep を付けた行は、ピッカーであらかじめ選択され、--yolo でエクスポートされます。以降のすべての処理（review、finalize、ゲート）は、どちらの場合も同じファイルを読み込みます。エンジンはこのスキルに scripts/funnel.py として同梱されています。

Direction export (scripts/export-direction.sh)

direction は購入単位です。エージェントが文章を判定することなくエクスポートされる、名前付きのテーマセットです。この経路が存在するのは、パートナーが再確認できる選択は再現可能でなければならず、モデルが文章を読む方法では再現可能にならないためです。

bash scripts/export-direction.sh --direction-file DIR.json -o OUT --yolo

上記のパイプラインと異なる点、そしてそれがこの経路の要点です。スクリーニングのステップはありません。 ファネルを通過した項目はそのままdecisions.tsvに書き込まれるため、記入するscreen.tsvの行はありません。ファネルの表を読んで、何かが壊滅的に間違っている場合に実行を中止してもかまいません。candidates.tsv、screen.tsv、decisions.tsv、またはファネルの出力を編集したり、行をkeep/dropに選んだりしてはいけません。そうすると、再現可能な選択があなたの判断に置き換わります。この経路が取り除くのは、まさにその点です。

数値は1つのグローバルポリシーにまとめられています。scripts/policy.jsonは共通の品質基準であり、エンジンは自身と同じ場所にあるこのファイルを解決します。ファイルがない場合はデフォルト値を使わず、エラーになります。テーマファイル（themes/<name>.json）にはテーマの識別情報のみを保持します。つまり、keywords、label、来歴、およびそのテーマに対してポリシーのキーを置き換える任意のoverrideです（翻訳ではメッセージごとの下限を移動し、ロールプレイではツールの上限を厳しくし、themes/coding.jsonではコーディングシグナルの単語リストを肯定的なトピックとして読み取ります）。directionファイルはテーマを指定し、購入条件によって制約する項目があればoverrideを持ちます。非コードのdirectionでは、ルートのoverrideで「非コード」を定義する単語リストexclude_keywordsを指定します。値はキーごとに合成され、後の値が優先されます。flags、directionのエントリー、directionのルート、テーマ、グローバルポリシーの順です。nullはキーをクリアし、空のリストはそのステージをOFFにします。報告時にしきい値を繰り返してはいけません。キー名を示してください。

2つの長さ制御は別々のものです

短いセッションを除外しないようにする指定は--min-linesです。このスクリプト（およびscan）におけるFILEの行数下限です。0を渡すと、短いことを理由にスキャン済みファイルが除外されることはありません。これはフラグであり、この経路で設定できる唯一の長さ制御です。

セッション内のMESSAGESが十分に長いかどうかは、別のポリシーで決まります。メッセージごとの文字数下限は、グローバルポリシーのキーmin_user_msg_charsに設定されており、ファネルのL5 lengthステージで適用されます。テーマまたはdirectionのoverrideで置き換えることができ、翻訳のテーマでは置き換えています。ランナーにはこの値を指定するオプションがありません。directionの選択はポリシーとそのoverrideだけから再現できなければならないためです。そのため、--min-lines 0で実行しても、ユーザーの発話がこのキーの値を下回るセッションは除外されます。ファネルの表には、除外の理由（longest later user msg N < M）が正しく報告され、ランナーは変更が必要なキーを出力します。報告時にはそのキー名を示してください。値を繰り返してはいけません。

対処可能なエラーが2つあります。致命的なエラーではなく、どちらもユーザーが対応するものです。

• python3を使用できない。 エンジンはPythonで動作し、代替手段はありません。スクリプトの scoop install python／winget install Python.Python.3.13の案内を示し、インストールして再試行するかどうかを確認してください。独自の意味的スクリーニングに置き換えてはいけません。
• 認証情報の形式が見つかった。 デフォルトでは、該当するセッションは納品物から除外され、書き込まれません。実行時には除外ごとに（ソースと認証情報の種類）および件数が出力されるため、その一覧をユーザーに報告してください。残りは通常どおり納品され、マニフェストに除外情報が記録されます。 --allow-credentialsを指定すると、該当するセッションも含まれます。これは明示的な人間の判断であり、マニフェストに記録されます。選択肢として提示し、独断で追加してはいけません。 --credential-hard-gateを指定すると、バッチ全体が拒否されます（終了コード3、何も書き込まれません）。どの設定でも、納品されるセッションの秘匿情報は削除されません。共有前に確認してください。

コレクション（funnel.py collect）— 第三の姿勢

配信ではフィルタリングを行い、コレクションでは注釈を付けます。collect CANDIDATES.tsv OUTDIR [--theme NAME] [--max-first-prompt-chars N] は、DESIGN.md § Collection and labeling で説明されている、上流工程の再現率優先の姿勢です。モデルのトークンはゼロで、しきい値はなく、グローバルポリシーは読み込まれません。除外されるのは、構造的に処理不能な行（unparseable）とバイト単位で同一のファイル（exact_duplicate）だけです。それ以外はすべて、すべてのエンリッチ列と注釈列を含む OUTDIR/pool.tsv に格納されます。また、各行につき自己完結型の行カードが OUTDIR/row-cards.jsonl に1件ずつ格納されます（最初のプロンプト、件数、フラグ、テーマの一致箇所を含み、購入者自身のモデルで判断するのに数百トークンで済みます）。さらに、除外されたすべての行とその理由を記載した dropped.tsv も作成されます。--theme NAME は theme_hits にキーワードを追加するだけで、しきい値には影響しません。プールをスクリーニング、順位付け、間引きしないでください。適合性の判断は後続のラベラーが行います。このモードでは、行カードを見ればまだ売れる可能性のあるものを何も失わないことを保証します。列ごとのリファレンスについては、エンジンの docstring と FUNNEL.md § Collection mode を参照してください。

スクリーニング（ステージ2）

scan は2つのファイルを書き出します。参照用の candidates.tsv（7列）と、同じ行に末尾の2列 suggested および reason を追加した screen.tsv です。この2列には見出しが付いており、値は空欄になっています。ステージ2では、screen.tsv をその場で編集します。 別のファイル名を新たに作らないでください（以前の実行で作成された candidates.screen.tsv は正式な仕様ではありません）。また、新しいファイルを一から作成しないでください。review と finalize は OUT/screen.tsv／OUT/decisions.tsv をそのまま読み込みます。行ごとに次の値を入力してください。

• suggested：keep または drop（この2語のみ）
• reason：根拠を1行で記入（タブや改行は不可。ファイルはTSVです）

その後、review --ui tsv を実行すると、suggested をデフォルト値として decision に設定した decisions.tsv が作成されます。人間が編集するのは、提案に同意できない行だけです。

引き渡しゲート（ここで停止してください。これはあなたが決めることではありません）

まず、リクエストに応じて経路を選択します。 NON-CODE セッションを納品用にエクスポートする場合、デフォルトではノーコード方向ランチャー（session-export-nocode）を使用します。ランチャーは設計上、無人で実行されるため、常に --yolo を実行し、引き渡しも通過すべきゲートもありません。このセクションのステージングパイプライン（スクリーニング、引き渡しゲート、ユーザー承認後の確定）は、提供済みの方向では対応できないリクエストと、行ごとに確認したいユーザー向けです。通常の非コードエクスポートのリクエストを、好みでステージング経路に回してはいけません。それは、方向のデフォルト設定によって取り除くべき気分次第の経路選択です。

保持するか破棄するかの判断は、ユーザーに委ねられています。あなたのスクリーニングはあくまで推奨であり、決定ではありません。確定の意味は、次の2つの経路で異なります。

• 対話型（pick-sessions.sh / .ps1 エントリーポイント / open-review.sh）： fzf 内でユーザーが ENTER を押すことが承認となり、その直後に確定が自動実行されます。それ以上、何も尋ねてはいけません。
• ヘッドレス：finalize はエージェントに委任されるインターフェースであり、以下のゲートを通過した後に限り、正当に実行できます。

ステージ2の後は、decision に何かを書き込んだり finalize を実行したりする前に、必ず停止してユーザーに選択肢を提示してください。

1. スクリーニングの概要を提示します。候補数、保持と判定した数、破棄の理由（理由ごとに1行にまとめます）。
2. その後、ユーザーのために対話型ピッカーを起動します。これは提示する選択肢ではなく、デフォルトの動作です。 Windows では pick-sessions.ps1 を実行します（WSL では pick-sessions.sh を実行します）。スクリーニング済みのリスト上にピッカーウィンドウが開き、ユーザーが fzf 内で ENTER を押すと、確定と検証が一度に行われます。あなた自身で起動してかまいません。起動方法を説明するだけで済ませたり、テキストでの返信を求めたりしてはいけません。ピッカーを開けない場合（デスクトップ環境のない純粋な Linux 環境）に限り、package 化されたランチャーをユーザーに渡します。curate-sessions.sh package を実行し、任意のターミナルで bash open-review.sh を実行するよう伝えてください。
3. テキストのみでの確認（「返信 确认导出」）は、ユーザーがピッカーを明示的に拒否した場合、またはターミナルを開けない場合の代替手段です。自分で何も入力してはいけません。ユーザーが decisions.tsv を編集するか、正確な変更内容を指示します。その後に限り、ユーザーの代理として finalize を実行してください。ヘッドレス経路では、すべてのエージェントにこのゲートを伝えるため、review --ui tsv は終了時にこのゲートを表示します。

decision 列を自分で埋めて確定してはいけません。実際に2回、そのように実行されました。その結果、ユーザーはエクスポートを依頼したにもかかわらず、保持・破棄の一覧を一度も見ることなくエクスポートされました。ユーザーが承認していないエクスポートは、すべてのコピーがバイト単位で同一だと検証されていても、タスクの完了とはなりません。

例外条項：--yolo（明示的なオプトアウトの場合のみ）

ユーザー自身の言葉で、レビューを明示的にオプトアウトしている場合（「直接导出」、「不用我看」、「just export it」など）は、pick-sessions.sh --yolo（または finalize --yolo）を実行します。ピッカーはスキップされ、スクリーニング済みの keep 行がエクスポートされます（スクリーニングされていない場合は、すべての候補が対象です）。マニフェストには mode=yolo, reviewed=false, approved_by=user-opt-out が記録されます。整合性チェックはスキップされません。sha256 と cmp によって、すべてのコピーが引き続き検証されます。Yolo が正当化されるのは、明示的な表現がある場合のみです。簡潔さ、沈黙、またはユーザーが忙しそうなことから推測してはいけません。ユーザー自身による明示的なオプトアウトがなければ、上記の通常のゲートを実行してください。

方向指定の経路では、この条項がすでにデフォルトになっています。session-export-nocode ランチャーは常に --yolo を渡し（マニフェストには batch_confirmed=false が記録されます）、--confirm を指定するとバッチ単位の [y/N] 確認ポイントが復元されます。上記の表現要件は、レビューがデフォルトとなるステージング経路と対話型経路に適用されます。

メタデータ行ではなく、文章の内容から判断してください。6 列目（first_prompt）はトリアージ用のヒントであり、空の場合があります。Codex は <environment_context>、AGENTS.md、スキルの足場情報をユーザーメッセージとして書き込みますが、これらは内容として報告されるのではなく、足場情報として取り除かれます。first_prompt が空であることは、セッションに人間が作成した冒頭ターンがなかったことを意味します。それ自体が drop の判断材料になります。

Codex はこれらの挿入ブロックを通常の message 項目としてマークするため、payload.type == "message" だけで選択する読み取り側は、約 80 行のシステム定型文も取り込んでしまいます。payload.role を user または assistant に限定してください。

finalize が読み取るのは decision 列のみです。そのため、人間は 1 つのフィールドを編集するだけで、あなたの suggested 値を上書きできます。

コーパスの検証

finalize は、セッションごとに source、kept_as、sha256 を記録します。コーパスを引き渡す前に、すべてのコピーがバイト単位で同一であることを確認してください。

jq -r '.[] | "\(.source)\t\(.kept_as)"' /tmp/cur/manifest.json > /tmp/pairs.tsv
while IFS=$'\t' read -r s d; do cmp -s "$s" "$d" || echo "MISMATCH $s"; done < /tmp/pairs.tsv

まずペアのリストをファイルに書き出してください。プロセス置換からループに入力すると（done < <(jq …)）、ジョブをバックグラウンドで実行したり中断したりした際に read がパイプ上でブロックされたままになり、失敗せずにハングします。

ピッカーは確定後にこのチェックを実行し、verified: N/N copies byte-identical と表示します。

オプション

scan：

• --agent claude|codex|both（デフォルトは both）
• --workspace SUBSTR — セッションの実際の cwd に対する部分文字列
• --topic REGEX — 抽出した文章に対する拡張正規表現
• --since YYYY-MM-DD
• --min-lines N — スタブセッションを除外します。ファイルの行数の下限であり、グローバルポリシーのメッセージ単位の下限とは無関係です（方向指定のエクスポートを参照）

review：

• --ui fzf（fzf がある場合のデフォルト）または --ui tsv — tsv は手動編集用の decisions.tsv を出力します。ヘッドレス経路のステップ 3 に相当します
• --resume — decisions.tsv にすでにある判断を保持します

finalize：

• --from FILE — デフォルト以外の decisions TSV を読み取ります
• --yolo — マニフェストに mode=yolo, reviewed=false を記録します（レビューなしの実行のみ。ゲートの例外条項を参照）
• --hardlink — コピーの代わりにリンクを作成します。読み取り専用の分析に限ります。後続の書き込みによって、リンク経由で元ファイルが破損する可能性があります。

validate は、TSV の列構成を確認し、decision 列の件数を集計します。

delivery は、引き渡し用に OUT/keep/ と OUT/manifest.json を 1 つのアーカイブにまとめます。形式はプラットフォームに従い（Windows Git Bash では zip、それ以外では tar.gz）、--out FILE でアーカイブ名を明示できます。マニフェストは常にアーカイブ内に含まれます。パッケージ化する前に、記録されているすべての sha256 を検証し、その後アーカイブを読み戻して確認します。パッケージ化するものがない場合は、空のアーカイブを作らずに処理を拒否します。

pick-sessions.sh は -a/--agent、-w/--workspace、-t/--topic、--since、-n/--min-lines、-o/--out、-y/--yes、--review-only、--yolo、--no-finalize、--stay、-h を受け付けます。

出力ディレクトリ

pick-sessions.sh は日付とエージェント名を含むデフォルトのパス（./curated-<agent>-<YYYYmmdd-HHmm>）を提案し、対話形式で確認します。 Enter キーで確定、e の後にパスを入力（Tab で補完）、q で終了、またはパスをそのまま入力できます。 -y を指定するとプロンプトを省略します。tty 以外から実行した場合も省略されるため、スクリプト実行がブロックされることはありません。 デフォルトのパスを固定すると、連続実行した際に同じディレクトリに結果が積み重なり、コーパスが単一の選択結果を示さなくなります。

より少ないセッションを選択して再実行すると、keep/ は追加ではなく置き換えられるため、コーパスは常に現在の判断と完全に一致します。

データソース

エージェント	パス	ワークスペースのフィールド	本文のフィールド
claude_code	~/.claude/projects/<munged>/<uuid>.jsonl	.cwd	.message.content（文字列、または {type:"text",text} の配列）
codex	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl	session_meta.payload.cwd	payload.type=="message" かつ payload.role が user／assistant の場合の .payload.content[].text

ここから、どちらも重要な次の2つのルールが導かれます。

• ワークスペースはディレクトリ名ではなく、フィールドから読み取ります。 claude は / を - に置き換えるため、-home-nixos-workspace-cits4012-a1 は …/cits4012/a1 と …/cits4012-a1 のどちらなのか判別できません。
• トピックの照合対象は、抽出した本文だけにします。 生の JSONL 行のバイト列を照合すると、base64 添付ファイルや tool_result ペイロードにヒットし、確信度は高くても無意味な結果になります。

操作環境

このスキルそのものがプロダクトです。環境ごとの対話型 UX は、「Windows 側のターミナルを起動できるか」という1つの質問で決まります。その答えによって、ほかのすべてが決まります。

環境	対話型ピッカー	tty が使用できない場合
Windows Git Bash（ネイティブ）	Windows Terminal を起動し、Git Bash を実行	段階的なパイプライン
WSL（Windows デスクトップにアクセス可能）	Windows Terminal を起動し、wsl.exe を実行	段階的なパイプライン
純粋な Linux／サーバー	なし — 起動できる統合ターミナルはありません。呼び出し元にすでに tty がある場合（ユーザーが自身のターミナルで review --ui fzf を実行する場合）は動作します	段階的なパイプライン、またはパッケージ化されたランチャー

「段階的なパイプライン」とは、対話なしで完了する方法です。screen → review --ui tsv → 編集 → finalize（「パイプライン」を参照）。ヘッドレス環境でユーザー用のターミナルがない場合、curate-sessions.sh package は、後からユーザー自身のターミナルで実行できるワンクリックランチャーを書き出します。これが純粋な Linux 環境向けの対話型 UX です。

tmux／zellij はユーザー用のウィンドウ起動には使用しません。TUI をプログラムから操作するエージェント向けの、非公開の内部テストハーネスとしてのみ存在します。

セッションは両方の側に保存されます。scan は、現在の HOME がある側を読み取ります

scan は、スクリプトを実行している環境の $HOME/.claude/projects と $HOME/.codex/sessions を読み取ります。 WSL 内で実行すると、Linux 側のディレクトリが対象になります。Windows 側のディレクトリ（/mnt/c/Users/<you>/.claude/projects、 /mnt/c/Users/<you>/.codex/sessions）も同じファイル形式ですが、自動ではスキャンされません。これらも含めるには、その HOME を指定してスクリプトを実行します。

HOME=/mnt/c/Users/<you> bash $C scan -o /tmp/cur-win --agent both

（WSL から実行しても問題ありません。形式は同じで、Windows の cwd は / 区切りに正規化されるため、--workspace による照合も同じように機能します。）

WSL：表示可能なターミナルがない場合、Windows 側でピッカー用のターミナルを開きます

WSL シェルに実際のターミナルがある場合、pick-sessions.sh はそのまま実行されます。ない場合（ツール呼び出し、CI ステップ、または対話型でないコンテキストからの起動時）は、Windows 側のターミナルを要求し、次の順序でその中からピッカーを実行します。

1. wt.exe -- wsl.exe -d $WSL_DISTRO_NAME — Windows Terminal（推奨）
2. cmd.exe /c start … wsl.exe — 通常のコンソールウィンドウ

起動は要求されるだけで、確認されるわけではありません。wt.exe は起動の委任が完了した時点で 0 を返すため、「要求した」結果、表示可能なウィンドウが現れないこともあります（デスクトップとの接続が切れている、サービスセッションなど）。そのため、親プロセスは起動メッセージとともに段階的なパイプラインを表示して、終了コード 0 で終了します。ウィンドウが表示されなかった場合は、表示された段階的なコマンドを実行してください。

Windows：bashをネイティブに実行する（Git Bash / MSYS）

スクリプト全体はMSYS上で実行され、WSLは関与しません。これはWindowsネイティブの操作環境です。Windowsでは、bash xxx.shではなく.ps1ラッパーを実行してください。 scripts\pick-sessions.ps1 / scripts\curate-sessions.ps1はGit Bashを見つけて、実際のスクリプトをGit Bashで再実行するため、呼び出し元のシェル（cmd、PowerShell、またはbashがWSLのbashを指すエージェント）は関係ありません。エントリーポイントは2つあり、意図も異なります。.ps1ラッパーは「使いたいセッションはWindows側にある」という意味です。WSL内で.shを実行する場合は、Linux側のセッションを対象にします。スクリプトが環境からその意図を推測することはできないため、PATHにあるシェルを基準にエントリーポイントを選ばないでください。

Git Bashがない場合、ラッパーはインストール方法を示して終了します（winget install Git.Git）。

セットアップに必要なのは2つのパッケージだけです。MSYSには、その他のPOSIXユーザーランドがすでに含まれています。

scoop install jq ripgrep          # or: winget install jqlang.jq BurntSushi.ripgrep.MSVC

TTYがない状態でpick-sessions.shを実行すると、Git Bashを実行するWindows Terminalが起動し、ピッカーに実際のTTYが割り当てられます。

スクリプトの対象として、Windows側のセッションツリーを指定してください。~/.codexと~/.claudeはC:\Users\<you>\…に対応しており、同じファイル形式のデータが格納されています。