claude-code-conductor 2.19.0__tar.gz → 2.21.0__tar.gz

{claude_code_conductor-2.19.0 → claude_code_conductor-2.21.0}/.claude/breaking-changes.txt

@@ -5,3 +5,4 @@
 # Lines starting with '#' are comments. Blank lines ignored.
 
 v2.11.0|summarize-memory agent + skill removed; replaced by `c3 recall`|summarize-memory エージェント / skill を完全廃止。代替は `c3 recall` の意味検索。
+v2.20.0|hooks/schema.sql removed; SQLite schema is now managed by c3/migrations/ (auto-applied at session_start)|hooks/schema.sql を削除しました。SQLite スキーマは c3/migrations/ (wheel 内) で管理され session_start で自動適用されます。

{claude_code_conductor-2.19.0 → claude_code_conductor-2.21.0}/.claude/deletions.txt

@@ -37,3 +37,6 @@ skills/phase-c-plan/SKILL.md
 skills/phase-d-implement/SKILL.md
 skills/phase-debug/SKILL.md
 skills/phase-e-review/SKILL.md
+
+# ---- v2.20.0: schema.sql を c3/migrations/ へ移行 ----
+hooks/schema.sql

{claude_code_conductor-2.19.0 → claude_code_conductor-2.21.0}/.claude/docs/config-policy.md

@@ -24,6 +24,7 @@
 .dev/hooks/                            配布元専用 hook（配布されない）
 src/c3/_excludes.py                    wheel 除外パターン（配布元のビルド制御）
 hatch_build.py                         _excludes.py の重複定義（ビルド時専用）
+src/c3/migrations/                     SQLite schema migration SQL ファイル群（Python package・wheel 同梱・.claude/ 配下ではないため 3 ファイル同期対象外）
 ```
 
 ### 1-2. 利用先プロジェクト（C3 ユーザー向け）
@@ -111,7 +112,7 @@ hatch_build.py                         _excludes.py の重複定義（ビルド
 
 | # | カテゴリ | 配布 | c3 update が更新 | 理由 |
 |---|---|---|---|---|
-| 1 | `.claude/hooks/*.py` | ○ | ○ | Claude Code lifecycle hook の実体。配布先で動作する。例外: `subagent_log.py` のみ除外（個人デバッグ用） |
+| 1 | `.claude/hooks/*.py` | ○ | ○ | Claude Code lifecycle hook の実体。配布先で動作する。例外: `subagent_log.py` のみ除外（個人デバッグ用）。v2.20.0 で `hooks/schema.sql` を削除し SQLite スキーマは `src/c3/migrations/` に移管 |
 | 2 | `.claude/agents/*.md` | ○ | ○ | ペルソナ定義。配布先で読まれる。例外: `tdd-develop.md` のみ除外（v2.1.0 廃止） |
 | 3 | `.claude/skills/*/` | ○ | ○ | オーケストレーション/ユーティリティ skill 定義（`scripts/` / `templates/` 等サブディレクトリ含む）。例外: `worktree-tdd-workflow/*` のみ除外（v2.1.0 廃止） |
 | 4 | `.claude/rules/*.md` | ○ | ○ | C3 配布デフォルトルール（常時注入対象） |

{claude_code_conductor-2.19.0 → claude_code_conductor-2.21.0}/.claude/hooks/session_start.py

@@ -12,22 +12,23 @@
 設計判断:
 - 旧 3 ファイルを統合することで SessionStart hook は本ファイル 1 本のみで完結
 - init-session SKILL.md からの手動 2 回呼び出しが不要になる
-- 旧 init_c3_db.py の `apply_schema()` / `SCHEMA_VERSION` は test 互換性のため
-  module レベルでそのまま公開する
+- v2.20.0 で apply_schema() を c3.migrate.apply_pending_migrations() に委譲。
+  SCHEMA_VERSION / SCHEMA_PATH 定数および schema.sql は廃止。
 """
 
 from __future__ import annotations
 
 import json
+import logging
 import os
 import shutil
-import sqlite3
 import sys
 import tempfile
-from datetime import datetime, timezone
 
 from session_utils import is_worktree
 
+logger = logging.getLogger(__name__)
+
 try:
     sys.stdin.reconfigure(encoding="utf-8")
     sys.stdout.reconfigure(encoding="utf-8")
@@ -71,7 +72,11 @@ def _run_clear_file_history() -> None:
         except FileNotFoundError:
             pass  # already deleted by another process between listdir and unlink/rmtree
         except Exception as e:
-            print(f'[clear-file-history] 削除に失敗: {name} ({e})', file=sys.stderr)
+            # [SR-R-001] shutil.rmtree / os.unlink のエラーメッセージには失敗したパス
+            # （FILE_HISTORY_DIR はホームディレクトリ配下のためユーザー名を含む）が
+            # 含まれる可能性がある。main() の SR M-1 修正と一貫して例外型名のみ出力する。
+            logger.debug('[clear-file-history] delete failed: %s', name, exc_info=True)
+            print(f'[clear-file-history] 削除に失敗: {name} ({type(e).__name__})', file=sys.stderr)
 
     print(f'[clear-file-history] {deleted} 件削除しました。')
 
@@ -113,7 +118,9 @@ def _run_enable_sandbox() -> None:
         try:
             settings = json.load(f)
         except json.JSONDecodeError as e:
-            print(f'[enable-sandbox] settings.json の JSON 解析に失敗しました: {e}')
+            # [SR-R-001] 一貫性のため例外型名のみ出力（JSONDecodeError 自体はパスを含まない
+            # が、SR M-1 / _run_clear_file_history と方針を統一する）。
+            print(f'[enable-sandbox] settings.json の JSON 解析に失敗しました: {type(e).__name__}')
             return
 
     if settings.get('sandbox', {}).get('enabled') is True:
@@ -132,7 +139,14 @@ def _run_enable_sandbox() -> None:
                 json.dump(settings, tmp_f, ensure_ascii=False, indent=2)
                 tmp_f.write('\n')
         except Exception:
-            os.close(fd)
+            # [CR-E-001] os.fdopen 成功後の書き込み例外では with __exit__ が既に
+            # fd を閉じているため、ここでの os.close(fd) は OSError(Bad file
+            # descriptor) を raise し元の例外を上書きしてしまう。os.fdopen 自体が
+            # 失敗して with に入らなかった場合のみ fd 解放が必要なので OSError を無視する。
+            try:
+                os.close(fd)
+            except OSError:
+                pass
             raise
         os.replace(tmp_path, settings_path)
         tmp_path = None  # os.replace が成功したので finally でのクリーンアップ不要
@@ -147,19 +161,10 @@ def _run_enable_sandbox() -> None:
 # 3. C3 SQLite DB 初期化（旧 init_c3_db.py）
 # =============================================================================
 
-# 現行スキーマバージョン。schema.sql に破壊的変更を入れたら +1 して
-# マイグレーションロジックを apply_schema() に追加する。
-SCHEMA_VERSION = 3  # v2.0.0 で PO 廃止に伴い po_results / po_status を削除
-
 _HOOKS_DIR = os.path.dirname(os.path.abspath(__file__))
 _CLAUDE_DIR = os.path.dirname(_HOOKS_DIR)
 STATE_DIR = os.path.join(_CLAUDE_DIR, 'state')
 DB_PATH = os.path.join(STATE_DIR, 'c3.db')
-SCHEMA_PATH = os.path.join(_HOOKS_DIR, 'schema.sql')
-
-
-def _now_iso() -> str:
-    return datetime.now(timezone.utc).astimezone().isoformat(timespec='seconds')
 
 
 def _ensure_state_dir() -> None:
@@ -167,38 +172,36 @@ def _ensure_state_dir() -> None:
     os.makedirs(STATE_DIR, exist_ok=True)
 
 
-def apply_schema(db_path: str = DB_PATH, schema_path: str = SCHEMA_PATH) -> None:
-    """schema_path の DDL を db_path の SQLite に適用する。
+def apply_schema(db_path: str = DB_PATH) -> list[str]:
+    """SQLite DB にスキーマ migration を適用する。
 
-    - WAL モードに切り替える
-    - schema.sql の CREATE TABLE IF NOT EXISTS 等を実行
-    - schema_version テーブルに現行バージョンを INSERT OR IGNORE
+    v2.20.0+: 実体は c3.migrate.apply_pending_migrations() に委譲。
+    schema.sql は廃止され、src/c3/migrations/ の連番 SQL ファイルで管理される。
 
-    冪等: 既存 DB に何度呼んでもエラーにならない。
+    戻り値: 今回新たに適用した migration version のリスト（例: ['001']）
     """
-    with open(schema_path, 'r', encoding='utf-8') as f:
-        ddl = f.read()
-
-    conn = sqlite3.connect(db_path, timeout=30)
+    from c3.migrate import apply_pending_migrations
     try:
-        # WAL モードを有効化（reader が writer をブロックしない）
-        conn.execute('PRAGMA journal_mode=WAL')
-        # 全 DDL を一括実行（CREATE TABLE IF NOT EXISTS なので冪等）
-        conn.executescript(ddl)
-        # スキーマバージョンを記録（既存なら無視）
-        conn.execute(
-            'INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)',
-            (SCHEMA_VERSION, _now_iso()),
+        return apply_pending_migrations(db_path)
+    except FileNotFoundError:
+        # migrations ディレクトリ不在（wheel が壊れている等）でもセッションは続行。
+        # [SR-R-001] 例外 e にはインストールパス（ユーザー名含む）が含まれるため
+        # stderr には固定文言のみ出力する。詳細は内部 logger（DEBUG）に残す。
+        logger.debug('apply_schema: migrations directory not found', exc_info=True)
+        print(
+            'warning: c3 migrations directory not found (wheel may be corrupted)',
+            file=sys.stderr,
         )
-        conn.commit()
-    finally:
-        conn.close()
+        return []
 
 
 def _run_init_c3_db() -> None:
     """C3 SQLite DB を初期化する."""
     _ensure_state_dir()
-    apply_schema()
+    # [CR-M-003] apply_schema() の戻り値（適用した migration version の list[str]）は
+    # 現状ログ・利用しない。セッション開始を妨げないことを最優先し、適用結果の通知は
+    # 行わない設計（将来 welcome メッセージ等で利用する場合はここで受ける）。
+    _ = apply_schema()
 
 
 # =============================================================================
@@ -222,7 +225,14 @@ def main() -> int:
             handler()
         except Exception as e:
             # 各ハンドラ失敗時は警告のみ（次のハンドラを継続）
-            print(f'[session_start:{label}] failed: {e}', file=sys.stderr)
+            # [SR-R-001] 例外メッセージには db_path 等のプロジェクトパスが含まれる
+            # 可能性がある（例: sqlite3.OperationalError）。stderr には例外型名のみ
+            # 出力し、詳細は内部 logger（DEBUG）に残す。
+            # NOTE(SR Info-2): exc_info=True は現状ハンドラ未設定で出力されないが、
+            # 将来 logging ハンドラを追加する場合はスタックトレースにインストールパスが
+            # 含まれる点に留意する。
+            logger.debug('[session_start:%s] handler failed', label, exc_info=True)
+            print(f'[session_start:{label}] failed: {type(e).__name__}', file=sys.stderr)
     return 0
 
 

{claude_code_conductor-2.19.0 → claude_code_conductor-2.21.0}/.claude/hooks/session_stop.py

@@ -89,6 +89,23 @@ def main() -> int:
     except Exception as e:
         print(f"[session_stop:consolidate_memory] failed: {e}", file=sys.stderr)
 
+    # Phase 3: usage_ingester — セッションログからコスト集計データを ingestion
+    # worktree session では起動しない（stop.run の is_worktree 判定と整合）
+    # 安全側動作: session_utils ロード失敗時や is_worktree 判定失敗時は ingester をスキップする。
+    # worktree 判定不能で誤起動するより skip を優先（except Exception で捕捉 → 早期終了）。
+    try:
+        session_utils_module = _load_module("session_utils")
+        if not session_utils_module.is_worktree(os.getcwd()):
+            session_id = payload.get("session_id")
+            transcript_path = payload.get("transcript_path")
+            if session_id and transcript_path:
+                from pathlib import Path as _Path  # noqa: PLC0415
+                from c3.usage_ingester import ingest_session  # noqa: PLC0415
+                project_dir = _Path(transcript_path).parent
+                ingest_session(session_id=session_id, project_dir=project_dir)
+    except Exception as e:
+        print(f"[session_stop:usage_ingester] failed: {type(e).__name__}", file=sys.stderr)
+
     return 0
 
 

{claude_code_conductor-2.19.0 → claude_code_conductor-2.21.0}/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## [2.21.0] - 2026-05-25
+
+**tier-routing コスト統合（データ収集基盤）**: Claude Code セッションログ（`~/.claude/projects/<slug>/<session>.jsonl` + subagent jsonl）を読み込み、モデル単価で USD 換算して c3.db に蓄積するデータ収集基盤を整備する。将来の cost-aware routing（v2.22.0）の土台。
+
+**スコープ注記**: 本リリースはデータ収集基盤のみ。cost-aware routing と tier_bandit のコスト列は v2.22.0 予定。
+
+### 機能追加
+
+- **`src/c3/pricing.py`（新規）**: Claude API モデルの USD/MTok 単価から token コストを計算する純関数モジュール。
+  `resolve_tier(model)`・`compute_cost_usd(...) -> tuple[float, bool]`・`known_models()` を提供。
+  Opus は世代で単価が 3 倍異なる（4.1/4=$15 系、4.5/4.6/4.7=$5 系）ため、具体パターン優先マッチ → tier 部分一致 fallback の 2 段構成を採用。
+  単価は 2026-05-25 公式取得値（出典 URL を docstring に明記）。
+
+- **`src/c3/migrations/002_agent_cost_runs.sql`（新規）**: `agent_cost_runs` テーブル・`usage_ingest_state` テーブル・インデックスを追加する migration。
+  PK=(session_id, agent_id, model) で「1 エージェント × 1 モデル = 1 行」の集約設計。
+  既存 event-based `agent_runs`（001）は一切変更しない。
+
+- **`src/c3/usage_ingester.py`（新規）**: セッションログ取り込みモジュール。
+  公開 API `ingest_session(*, session_id, project_dir, db_path=None) -> IngestResult`。
+  mainline / subagent jsonl を走査し、model 単位でトークンを合算して `insert_agent_cost_run` で upsert する。
+  session_id UUID validate・パストラバーサル防止・symlink スキップ・例外 type 名のみログ（SR-R-001 準拠）。
+
+- **`.claude/hooks/session_stop.py` Phase 3 追加**: セッション終了時に `ingest_session` を呼ぶ Phase 3 を追加。
+  worktree session では起動しない。例外握りつぶしで exit 0 を維持する。
+
+- **`c3 tier stats` の Agent 別コスト集計セクション追加**: `_collect_snapshot()` に `read_agent_cost_summary()` を追加し、human / JSON 両出力に `agent_cost` セクションを表示する。
+  mainline 行には「（マクロ集計・tier 学習対象外）」を明示。0 件のときは「（コストデータ未収集）」を表示。
+
+### 変更
+
+- **`src/c3/db.py`**: 4 ヘルパー追加（`insert_agent_cost_run` / `read_agent_cost_summary` / `get_ingest_offset` / `set_ingest_offset`）。既存 tier ヘルパー規約（DB 不在で静かに False/0/[]・WAL・busy_timeout）に準拠。
+
+- **`src/c3/__init__.py`**: `__version__` を `"2.20.0"` から `"2.21.0"` に更新。
+
+## [2.20.0] - 2026-05-25
+
+**SQLite schema migration 枠組み導入**: `.claude/hooks/schema.sql` の「冪等 DDL 一発実行」から、`src/c3/migrations/` の「連番 NNN_xxx.sql migration runner」へ移行する基盤を整備する。
+v2.18.0 の `deletions.txt` 機構・v2.19.0 の `breaking-changes.txt` 機構の初の実運用ドッグフーディングでもある。
+
+### 機能追加
+
+- **`src/c3/migrate.py`（新規）**: SQLite migration runner。
+  公開 API `apply_pending_migrations(db_path, migrations_dir=None) -> list[str]` および例外クラス `MigrationError(RuntimeError)` を提供。
+  `src/c3/migrations/` 配下の連番 SQL ファイルを昇順に適用し、適用済み migration を `schema_migrations` テーブルで管理する。
+  WAL モード / busy_timeout=5000ms を冒頭で設定（既存 `c3.db.BUSY_TIMEOUT_MS` を SSOT として参照）。
+
+- **`src/c3/migrations/001_initial.sql`（新規）**: 既存 `hooks/schema.sql` の DDL を逐語移植 + bootstrap。
+  `schema_migrations` テーブル新設、旧 `schema_version` テーブル DROP、`BEGIN;` / `COMMIT;` 明示記述による transaction 境界保証を含む。
+
+- **`src/c3/migrations/__init__.py`（新規）**: Python package marker（wheel 自動同梱のため）。
+
+- **`src/c3/migrations/README.md`（新規）**: 命名規約（`NNN_xxx.sql`）・`BEGIN;`/`COMMIT;` 必須運用ルール・002 以降の追加手順を記載。
+
+- **`schema_migrations` テーブル（新規）**: 適用済み migration の一覧を保持（`version TEXT PK`, `applied_at TIMESTAMP`）。
+  旧 `schema_version (version INTEGER PK, applied_at TEXT)` を置換。
+
+### 変更
+
+- **`.claude/hooks/session_start.py`**: `apply_schema(db_path)` の実体を `c3.migrate.apply_pending_migrations()` に委譲。
+  戻り値が `None` → `list[str]`（適用した migration version のリスト）に変更。
+  migrations_dir 不在時は `FileNotFoundError` を warning として stderr に出力し、セッションは続行する（exit 0 維持の既存方針踏襲）。
+
+- **`src/c3/__init__.py`**: `__version__` を `"2.19.0"` から `"2.20.0"` に更新。
+
+### 破壊的変更
+
+- **`hooks/schema.sql` 削除**: `.claude/hooks/schema.sql` をリポジトリから削除。
+  SQLite スキーマは `src/c3/migrations/` (wheel 内) で管理され、`session_start` で自動適用される。
+  利用先からの削除は `deletions.txt` 機構（v2.18.0）によって `c3 update` 実行時に処理される。
+
+- **`apply_schema` の `schema_path` 引数削除**: `session_start.py::apply_schema()` から `schema_path` 引数を完全削除（deprecation 期間なし）。
+  呼び出し側で `schema_path=` を渡している場合は削除が必要（`c3 update` 実行後のテストコード等）。
+
+### ドキュメント
+
+- **`.claude/docs/config-policy.md`**:
+  - §1-1 配布元ディレクトリ表に `src/c3/migrations/` を追加（Python package・wheel 同梱・3 ファイル同期対象外）
+  - §3 カテゴリ #1 hooks 備考に「v2.20.0 で `hooks/schema.sql` を削除、SQLite スキーマは `src/c3/migrations/` に移管」を追記
+
+- **`.claude/breaking-changes.txt`**: v2.20.0 エントリ追記（`hooks/schema.sql` 削除）
+
+- **`.claude/deletions.txt`**: `hooks/schema.sql` 追記（利用先からの自動削除を `c3 update` 経由で実現）
+
+### ドッグフーディング
+
+- **v2.18.0 `deletions.txt` 機構**: `hooks/` 配下の非テスト SQL ファイル削除の初の実運用事例（過去は `agents/` / `skills/` の `.md` のみ）。
+- **v2.19.0 `breaking-changes.txt` 機構**: v2.20.0 エントリを新規追加して MINOR bump 表示路を初通過させる。
+- **`scripts/extract_breaking_changes.py`**: `--dry-run` / 通常実行 / `--check` のフルライフサイクル運用。
+
+### 影響
+
+- **既存利用先**: `c3 update` 実行時に v2.20.0 breaking change が表示される（v2.19.0 以降の利用先）。
+  `.claude/hooks/schema.sql` は `c3 update` 実行時に自動削除される。
+  次回セッション開始時に `apply_pending_migrations` が `schema_migrations` テーブルを新設し 001 を適用する。
+  既存データ（`review_decisions` 等）は保持される。`schema_version` テーブルは削除される。
+
+---
+
 ## [2.19.0] - 2026-05-24
 
 **基盤整備リリース第 3 弾**: `c3 update` 実行時に breaking changes 表示 + MAJOR 承認プロンプトを導入する。

{claude_code_conductor-2.19.0 → claude_code_conductor-2.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-conductor
-Version: 2.19.0
+Version: 2.21.0
 Summary: Multi-agent orchestration framework for Claude Code with Codex/Cursor adapters (C3)
 Project-URL: Homepage, https://github.com/satoh-y-0323/claude-code-conductor
 Project-URL: Repository, https://github.com/satoh-y-0323/claude-code-conductor

{claude_code_conductor-2.19.0 → claude_code_conductor-2.21.0}/src/c3/__init__.py

@@ -1,3 +1,3 @@
 """Claude Code Conductor (C3) - multi-agent orchestration framework for Claude Code."""
 
-__version__ = "2.19.0"
+__version__ = "2.21.0"

{claude_code_conductor-2.19.0 → claude_code_conductor-2.21.0}/src/c3/cli_tier.py

@@ -89,7 +89,7 @@ def handle_stats(args: argparse.Namespace) -> int:
 
 
 def _collect_snapshot(db_path, recent_limit: int) -> dict[str, Any]:
-    """DB から tier_bandit / tier_recent_outcomes を読み snapshot dict を返す。"""
+    """DB から tier_bandit / tier_recent_outcomes / agent_cost を読み snapshot dict を返す。"""
     bandit_rows: list[dict[str, Any]] = []
     total_trials = 0
 
@@ -114,6 +114,8 @@ def _collect_snapshot(db_path, recent_limit: int) -> dict[str, Any]:
         db_path=db_path,
     )
 
+    agent_cost: list[dict[str, Any]] = c3_db.read_agent_cost_summary(db_path=db_path)
+
     if total_trials < _LEARNING_THRESHOLD:
         mode = "uniform"
     else:
@@ -127,6 +129,7 @@ def _collect_snapshot(db_path, recent_limit: int) -> dict[str, Any]:
         },
         "tier_bandit": bandit_rows,
         "recent_outcomes": recent_outcomes,
+        "agent_cost": agent_cost,
     }
 
 
@@ -166,3 +169,25 @@ def _render_human(snapshot: dict[str, Any]) -> None:
     print("== 学習データ記録チャネル ==")
     print("記録元: dev-workflow フェーズ E の最終承認時のみ（record_tier_outcome.py）")
     print("直接指示作業ではデータが溜まりません（設計通り）")
+    print()
+
+    print("== Agent 別コスト集計（agent_cost_runs） ==")
+    agent_cost = snapshot.get("agent_cost", [])
+    if not agent_cost:
+        print("（コストデータ未収集）")
+    else:
+        print(
+            f"{'agent_type':<16} {'runs':>5}  {'total_usd':>10}  "
+            f"{'in_tok':>9}  {'out_tok':>9}  {'cache_r':>9}  {'cache_w':>9}"
+        )
+        for row in agent_cost:
+            note = "  （マクロ集計・tier 学習対象外）" if row["agent_type"] == "mainline" else ""
+            print(
+                f"{row['agent_type']:<16} {row['runs']:>5}  "
+                f"${row['total_cost_usd']:>9.4f}  "
+                f"{row['input_tokens']:>9}  {row['output_tokens']:>9}  "
+                f"{row['cache_read_tokens']:>9}  {row['cache_create_tokens']:>9}"
+                f"{note}"
+            )
+    print()
+    print("（注: 本リリースはデータ収集基盤のみ。cost-aware routing は v2.22.0 予定）")

{claude_code_conductor-2.19.0 → claude_code_conductor-2.21.0}/src/c3/db.py

@@ -493,3 +493,250 @@ def read_tier_failure_rate(
 
     failures = sum(1 for r in rows if r[0] == 0)
     return failures / sample_count, sample_count
+
+
+# ---------------------------------------------------------------------------
+# usage-ingester: agent_cost_runs / usage_ingest_state ヘルパー（v2.21.0）
+# ---------------------------------------------------------------------------
+
+
+def insert_agent_cost_run(
+    *,
+    session_id: str,
+    agent_id: str,
+    agent_type: str,
+    description: str | None,
+    model: str,
+    attribution_skill: str | None,
+    input_tokens: int,
+    output_tokens: int,
+    cache_read_tokens: int,
+    cache_create_tokens: int,
+    total_cost_usd: float,
+    db_path: Path | None = None,
+) -> bool:
+    """agent_cost_runs に 1 行 upsert する。
+
+    PK=(session_id, agent_id, model) で「1 エージェント × 1 モデル = 1 行」。
+    同一 PK が既に存在する場合は全数値列・total_cost_usd・recorded_at を最新合算値に上書き。
+
+    Args:
+        session_id: セッション UUID。
+        agent_id: 'agent-<id>' または 'mainline'。
+        agent_type: meta.json の agentType / 'mainline'。
+        description: meta.json の description（任意）。
+        model: message.model 文字列。
+        attribution_skill: assistant レコードの attributionSkill（任意）。
+        input_tokens: 入力トークン数（jsonl 内合算値）。
+        output_tokens: 出力トークン数（jsonl 内合算値）。
+        cache_read_tokens: キャッシュ読み込みトークン数（jsonl 内合算値）。
+        cache_create_tokens: キャッシュ書き込みトークン数（jsonl 内合算値）。
+        total_cost_usd: compute_cost_usd が返した USD コスト。
+        db_path: c3.db のパス。省略時は locate_c3_db() で探索。
+
+    Returns:
+        upsert 成功時 True、DB 不在 / sqlite3.Error 時は静かに False。
+    """
+    if db_path is None:
+        db_path = locate_c3_db()
+        if db_path is None:
+            return False
+
+    from datetime import timezone as _tz  # noqa: PLC0415
+    now_iso = datetime.now(_tz.utc).isoformat(timespec="seconds")
+
+    try:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            conn.execute("PRAGMA journal_mode=WAL")
+            _apply_busy_timeout(conn)
+            conn.execute(
+                "INSERT INTO agent_cost_runs "
+                "(session_id, agent_id, agent_type, description, model, "
+                " attribution_skill, input_tokens, output_tokens, "
+                " cache_read_tokens, cache_create_tokens, "
+                " total_cost_usd, recorded_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
+                "ON CONFLICT(session_id, agent_id, model) DO UPDATE SET "
+                "  agent_type = excluded.agent_type, "
+                "  description = excluded.description, "
+                "  attribution_skill = excluded.attribution_skill, "
+                "  input_tokens = excluded.input_tokens, "
+                "  output_tokens = excluded.output_tokens, "
+                "  cache_read_tokens = excluded.cache_read_tokens, "
+                "  cache_create_tokens = excluded.cache_create_tokens, "
+                "  total_cost_usd = excluded.total_cost_usd, "
+                "  recorded_at = excluded.recorded_at",
+                (
+                    session_id, agent_id, agent_type, description, model,
+                    attribution_skill, input_tokens, output_tokens,
+                    cache_read_tokens, cache_create_tokens,
+                    total_cost_usd, now_iso,
+                ),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+        return True
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("failed to insert_agent_cost_run: %s", type(exc).__name__)
+        return False
+
+
+def read_agent_cost_summary(
+    *,
+    db_path: Path | None = None,
+    limit: int = 50,
+) -> list[dict]:
+    """agent_cost_runs を agent_type 別に集計した結果を返す。
+
+    SELECT agent_type, COUNT(*) runs, SUM(total_cost_usd), SUM(input_tokens),
+    SUM(output_tokens), SUM(cache_read_tokens), SUM(cache_create_tokens)
+    FROM agent_cost_runs GROUP BY agent_type ORDER BY total_cost_usd DESC LIMIT ?
+
+    Args:
+        db_path: c3.db のパス。省略時は locate_c3_db() で探索。
+        limit: 返す最大件数（デフォルト 50）。
+
+    Returns:
+        各行を dict にしたリスト。キー:
+        ``agent_type`` / ``runs`` / ``total_cost_usd`` /
+        ``input_tokens`` / ``output_tokens`` /
+        ``cache_read_tokens`` / ``cache_create_tokens``。
+        DB 不在 / テーブル不在 / エラー時は空リスト。
+    """
+    if db_path is None:
+        db_path = locate_c3_db()
+        if db_path is None:
+            return []
+
+    try:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            # WAL は書き込みヘルパー呼び出し時または migrate 時に設定済みの前提
+            # （既存 read_recent_outcomes 等の read ヘルパーと同方針 / CR-M-001）
+            _apply_busy_timeout(conn)
+            rows = conn.execute(
+                "SELECT agent_type, "
+                "       COUNT(*) AS runs, "
+                "       SUM(total_cost_usd) AS total_cost_usd, "
+                "       SUM(input_tokens) AS input_tokens, "
+                "       SUM(output_tokens) AS output_tokens, "
+                "       SUM(cache_read_tokens) AS cache_read_tokens, "
+                "       SUM(cache_create_tokens) AS cache_create_tokens "
+                "FROM agent_cost_runs "
+                "GROUP BY agent_type "
+                "ORDER BY total_cost_usd DESC "
+                "LIMIT ?",
+                (limit,),
+            ).fetchall()
+        finally:
+            conn.close()
+    except sqlite3.OperationalError as exc:
+        # テーブル不在（no such table）は [] を返す（DB 未初期化でも止めない）
+        logger.debug(
+            "read_agent_cost_summary: table not found or inaccessible: %s",
+            type(exc).__name__,
+        )
+        return []
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("read_agent_cost_summary: unexpected error: %s", type(exc).__name__)
+        return []
+
+    return [
+        {
+            "agent_type": row[0],
+            "runs": row[1],
+            "total_cost_usd": row[2],
+            "input_tokens": row[3],
+            "output_tokens": row[4],
+            "cache_read_tokens": row[5],
+            "cache_create_tokens": row[6],
+        }
+        for row in rows
+    ]
+
+
+def get_ingest_offset(
+    file_key: str,
+    *,
+    db_path: Path | None = None,
+) -> int:
+    """usage_ingest_state から処理済み行数（offset）を返す。
+
+    Args:
+        file_key: '<session>:mainline' / '<session>:agent-<id>'。
+        db_path: c3.db のパス。省略時は locate_c3_db() で探索。
+
+    Returns:
+        処理済み行数。行・テーブル不在・DB 不在は 0 を返す。
+    """
+    if db_path is None:
+        db_path = locate_c3_db()
+        if db_path is None:
+            return 0
+
+    try:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            # WAL は書き込みヘルパー呼び出し時または migrate 時に設定済みの前提
+            # （既存 read_recent_outcomes 等の read ヘルパーと同方針 / CR-M-001）
+            _apply_busy_timeout(conn)
+            row = conn.execute(
+                "SELECT last_offset FROM usage_ingest_state WHERE file_key = ?",
+                (file_key,),
+            ).fetchone()
+        finally:
+            conn.close()
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("get_ingest_offset: %s", type(exc).__name__)
+        return 0
+
+    return row[0] if row is not None else 0
+
+
+def set_ingest_offset(
+    file_key: str,
+    offset: int,
+    *,
+    db_path: Path | None = None,
+) -> bool:
+    """usage_ingest_state に offset を upsert する。
+
+    Args:
+        file_key: '<session>:mainline' / '<session>:agent-<id>'。
+        offset: 処理済み行数（= 次回開始行）。
+        db_path: c3.db のパス。省略時は locate_c3_db() で探索。
+
+    Returns:
+        upsert 成功時 True、DB 不在 / エラー時は静かに False。
+    """
+    if db_path is None:
+        db_path = locate_c3_db()
+        if db_path is None:
+            return False
+
+    from datetime import timezone as _tz  # noqa: PLC0415
+    now_iso = datetime.now(_tz.utc).isoformat(timespec="seconds")
+
+    try:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            conn.execute("PRAGMA journal_mode=WAL")
+            _apply_busy_timeout(conn)
+            conn.execute(
+                "INSERT INTO usage_ingest_state "
+                "(file_key, last_offset, last_processed_at) "
+                "VALUES (?, ?, ?) "
+                "ON CONFLICT(file_key) DO UPDATE SET "
+                "  last_offset = excluded.last_offset, "
+                "  last_processed_at = excluded.last_processed_at",
+                (file_key, offset, now_iso),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+        return True
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("failed to set_ingest_offset: %s", type(exc).__name__)
+        return False