dashcam-ai 0.4.0__tar.gz

dashcam_ai-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e . && pip install pytest ruff
+      - run: ruff check src tests
+      - run: pytest -q

dashcam_ai-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  id-token: write
+  contents: write
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+      - name: Create GitHub Release
+        run: gh release create "${{ github.ref_name }}" --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

dashcam_ai-0.4.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

dashcam_ai-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+## Setup
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e . && pip install pytest ruff
+pytest -q && ruff check src tests
+```
+
+CI runs the same on Python 3.10–3.13. Keep it green.
+
+## Ground rules
+
+- **Deterministic, read-only, tested.** Parsers never modify harness logs.
+- **Narrow beats bundle.** If a feature doesn't make the receipts more
+  trustworthy or more useful, it probably doesn't belong.
+- Every parser change needs fixture transcripts under
+  `tests/fixtures/<harness>/` and tests for: parsing, malformed input,
+  incremental resume, no-duplicate re-ingest.
+- Price updates touch **only** `src/dashcam/data/models.json`.
+- Never persist full prompts. Run new tool-input shapes through
+  `redact()` and add a test proving secrets don't land in SQLite.
+- Don't weaken `store.py`'s transaction discipline, WAL mode, or file
+  permissions without discussion.
+
+## Adding a harness
+
+See `docs/ARCHITECTURE.md`. The hard requirement: verify the log format
+against real harness output. An unverified parser doesn't ship.
+
+## Commits & PRs
+
+- Small, focused commits with clear messages.
+- PRs: describe what changed, what you verified, and how (tests, manual
+  runs). Link fixtures to their source format.
+- Be ready to defend every line — this project holds people's receipts.

dashcam_ai-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Varshith Puli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dashcam_ai-0.4.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: dashcam-ai
+Version: 0.4.0
+Summary: The dashcam for your AI coding agents — tamper-evident session receipts and cross-provider cost. Read-only.
+Project-URL: Homepage, https://github.com/Varshith-Kali/dashcam
+Project-URL: Repository, https://github.com/Varshith-Kali/dashcam
+Project-URL: Issues, https://github.com/Varshith-Kali/dashcam/issues
+Author: Varshith Puli
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,audit,coding-assistant,cost-tracking,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# dashcam
+
+**The dashcam for your AI coding agents.**
+
+[![CI](https://github.com/Varshith-Kali/dashcam/actions/workflows/ci.yml/badge.svg)](https://github.com/Varshith-Kali/dashcam/actions)
+[![PyPI](https://img.shields.io/pypi/v/dashcam-ai)](https://pypi.org/project/dashcam-ai/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/github/license/Varshith-Kali/dashcam)](LICENSE)
+
+*A dashcam doesn't stop the car. It records.*
+
+<img src="docs/assets/demo.svg" alt="dashcam today — sessions, tool calls, files touched, tokens and cost per model" width="720">
+
+</div>
+
+## The problem
+
+Your coding agents take hundreds of actions a day — reading files, running commands, calling models. When something goes wrong (a bad deploy, a surprise bill, an auditor's question), you have **no tape**:
+
+- **Harness logs exist but nobody reads them.** Claude Code writes every session to `~/.claude/projects/`, but it's raw JSONL exhaust — no digests, no cost, no verification.
+- **Your SIEM doesn't see it.** Agent activity lives on developer laptops. Nobody pays Splunk ingest pricing for "agent ran `ls` 400 times" — so the tool-call tape simply never reaches the SOC.
+- **Cost is invisible until the invoice.** Tokens scatter across providers and models with no per-session attribution.
+
+dashcam reads the logs your agents *already write* and keeps **tamper-evident receipts**: every tool call, every token, every dollar. Read-only. Local-first. Nothing leaves your machine unless you say so.
+
+## What it is
+
+- **Session receipts** — every agent session parsed from the harness's own logs into local SQLite, each row hash-chained (`sha256(prev_hash + record)`). `dashcam verify` proves the tape wasn't altered.
+- **Multi-harness** — Claude Code, Codex CLI, Gemini CLI, and opencode, each with a verified parser. `dashcam ingest` reads them all; `dashcam ingest --harness codex` reads one.
+- **Cross-provider cost** — token usage converted to USD per provider/model from a community price table. No proxy, no MITM, no behavior change.
+- **`dashcam today`** — the daily digest: sessions, tool calls, files touched, tokens, spend — plus **unusual-session flags** when a session costs or calls tools far above its project's baseline. `dashcam today --project foo` filters to one project.
+- **Signed bundles** — `dashcam export --format bundle --session <id>` emits an Ed25519-signed portable receipt anyone can verify offline with `dashcam verify-bundle`. The artifact you hand to an auditor.
+- **`dashcam serve`** — a localhost-only read-only timeline UI: today's stats, anomaly flags, recent sessions, per-session detail with chain-integrity check.
+- **`dashcam brief`** — optional BYOK narration: your own API key (OpenAI-compatible or Anthropic) turns the digest into a plain-English briefing. Off by default; only aggregate stats are ever sent.
+- **SIEM-ready** — `dashcam export --format hec` emits Splunk HEC events. dashcam is the edge sensor; your SIEM stays the system of record. See [docs/SIEM.md](docs/SIEM.md).
+
+## What it is not
+
+- **Not a firewall.** dashcam never blocks, prompts, or restrains your agent. Blocking sidecars get bypassed by the agent, fatigue the user, and get uninstalled — we chose the other side of that trade on purpose. The tape doesn't lie, and it doesn't nag.
+- **Not a cloud service.** No accounts, no servers, no telemetry. Receipts live in `~/.dashcam/receipts.db`.
+
+## Already have Splunk?
+
+Then you know the gap: your SIEM sees EDR process events and proxy logs — *that something ran* — but not the agent's tool-call sequence. dashcam records the tape where the work happens (free, zero-config) and forwards clean JSONL to HEC when you're ready:
+
+```bash
+dashcam export --format hec | curl -H "Authorization: Splunk $HEC_TOKEN" \
+  --data-binary @- https://your-splunk:8088/services/collector/event
+```
+
+Regulators are asking for exactly this artifact: the EU AI Act (Art. 12, enforceable since Aug 2026) requires high-risk AI systems to keep **tamper-evident** event logs; SOC 2 and ISO 42001 demand the same discipline. dashcam produces the receipt; your SIEM keeps it. Full mapping in [docs/SIEM.md](docs/SIEM.md).
+
+## Quickstart
+
+```bash
+pipx install dashcam-ai        # or: pip install dashcam-ai
+dashcam demo               # 60-second tour on a scratch DB — your receipts stay clean
+dashcam ingest             # read all your agents' session logs (read-only, resumable)
+dashcam today              # what did my agents do today? (+ unusual-session flags)
+dashcam serve              # localhost timeline UI at http://127.0.0.1:8321
+dashcam brief              # BYOK plain-English briefing (needs your API key)
+dashcam runs               # sessions with tool calls, tokens and cost each
+dashcam verify             # prove the receipts weren't tampered with
+dashcam export --format bundle --session <id>  # signed receipt for auditors
+dashcam export             # dump receipts as JSON (or --format hec for Splunk)
+```
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["Agent transcripts<br/>Claude Code · Codex · Gemini · opencode"] -->|"read-only parse<br/>(nothing is modified)"| B["dashcam ingest"]
+    B -->|"hash-chained,<br/>one ACID txn per file"| C[("SQLite<br/>~/.dashcam/receipts.db")]
+    C --> D["today · brief<br/>(digest + anomaly flags)"]
+    C --> E["serve<br/>(localhost UI)"]
+    C --> F["verify<br/>(chain check)"]
+    C --> G["export --format hec"]
+    G --> H["Splunk / SIEM"]
+    C --> I["export --format bundle"]
+    I --> J["Signed receipt<br/>(auditors, clients)"]
+```
+
+Each recorded row seals the previous one into a SHA-256 chain. Delete or alter a row and `dashcam verify` fails — the same tamper-evidence idea behind signed audit logs, running entirely on your laptop. Details in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Security
+
+Full threat model in [SECURITY.md](SECURITY.md). The short version:
+
+- **Tamper-evident, not tamper-proof** — stated honestly, with the upgrade path documented.
+- **Secret redaction** — command text is scrubbed for recognizable secrets before persistence; full prompts are never stored.
+- **Local-first** — receipts never leave your machine. The only network calls dashcam ever makes are the ones you explicitly opt into: `brief` with your own API key. No telemetry, ever. DB is `0600`, directory `0700`.
+- **Crash-safe** — per-file ingestion is one ACID transaction; concurrent writers can't fork the chain (WAL + `BEGIN IMMEDIATE`).
+
+## Cost data
+
+Prices live in [`src/dashcam/data/models.json`](src/dashcam/data/models.json) (USD per 1M tokens). Providers change prices; when they do, send a PR that touches *only* that file. If the table is stale, drop your own `~/.dashcam/pricing.json` (same format) — it overrides the packaged table without a reinstall.
+
+## Roadmap
+
+- **v0.1** — the tape: Claude Code transcripts, hash-chained receipts, cost, digest, demo, verify, SIEM export
+- **v0.2** — universal tape: Codex CLI + Gemini CLI parsers, unusual-session flags, Ed25519 signed bundles
+- **v0.3** — opencode parser (SQLite), `dashcam serve` localhost timeline UI, `dashcam today --project`
+- **v0.4** — `dashcam brief`: optional BYOK narration (your key, off by default, aggregates only)
+
+The roadmap is complete. What's next is driven by real usage — file an issue with
+what your agents do that dashcam doesn't capture yet. See [docs/ROADMAP.md](docs/ROADMAP.md).
+
+## Honest comparisons
+
+- **vs. blocking sidecars** (pre-execution firewalls): they restrain, we record. Restraint gets bypassed by a capable agent and fatigues users; recording stays out of the agent's way and never nags. Different jobs. (Honest scope note: we only see what the harness actually writes to its logs.)
+- **vs. session scorers** (e.g. `agent-dashcam`): they grade your agent's *quality*; we keep the *evidence*. The tape comes before the verdict.
+- **vs. agentmetry** (closest in spirit — local-first flight recorder, hash-chained): they go wider (MITRE mapping, detections, DLP, blocking modes) via IDE hooks; we stay narrow (receipts + cost + digest) and read-only — no hooks to install, none to bypass. Early days for both; pick the philosophy you want.
+
+## Contributing
+
+PRs welcome. The bar: deterministic, read-only, tested. Every parser change needs fixture transcripts in `tests/`; price updates touch only the pricing file. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

dashcam_ai-0.4.0/README.md

@@ -0,0 +1,122 @@
+<div align="center">
+
+# dashcam
+
+**The dashcam for your AI coding agents.**
+
+[![CI](https://github.com/Varshith-Kali/dashcam/actions/workflows/ci.yml/badge.svg)](https://github.com/Varshith-Kali/dashcam/actions)
+[![PyPI](https://img.shields.io/pypi/v/dashcam-ai)](https://pypi.org/project/dashcam-ai/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/github/license/Varshith-Kali/dashcam)](LICENSE)
+
+*A dashcam doesn't stop the car. It records.*
+
+<img src="docs/assets/demo.svg" alt="dashcam today — sessions, tool calls, files touched, tokens and cost per model" width="720">
+
+</div>
+
+## The problem
+
+Your coding agents take hundreds of actions a day — reading files, running commands, calling models. When something goes wrong (a bad deploy, a surprise bill, an auditor's question), you have **no tape**:
+
+- **Harness logs exist but nobody reads them.** Claude Code writes every session to `~/.claude/projects/`, but it's raw JSONL exhaust — no digests, no cost, no verification.
+- **Your SIEM doesn't see it.** Agent activity lives on developer laptops. Nobody pays Splunk ingest pricing for "agent ran `ls` 400 times" — so the tool-call tape simply never reaches the SOC.
+- **Cost is invisible until the invoice.** Tokens scatter across providers and models with no per-session attribution.
+
+dashcam reads the logs your agents *already write* and keeps **tamper-evident receipts**: every tool call, every token, every dollar. Read-only. Local-first. Nothing leaves your machine unless you say so.
+
+## What it is
+
+- **Session receipts** — every agent session parsed from the harness's own logs into local SQLite, each row hash-chained (`sha256(prev_hash + record)`). `dashcam verify` proves the tape wasn't altered.
+- **Multi-harness** — Claude Code, Codex CLI, Gemini CLI, and opencode, each with a verified parser. `dashcam ingest` reads them all; `dashcam ingest --harness codex` reads one.
+- **Cross-provider cost** — token usage converted to USD per provider/model from a community price table. No proxy, no MITM, no behavior change.
+- **`dashcam today`** — the daily digest: sessions, tool calls, files touched, tokens, spend — plus **unusual-session flags** when a session costs or calls tools far above its project's baseline. `dashcam today --project foo` filters to one project.
+- **Signed bundles** — `dashcam export --format bundle --session <id>` emits an Ed25519-signed portable receipt anyone can verify offline with `dashcam verify-bundle`. The artifact you hand to an auditor.
+- **`dashcam serve`** — a localhost-only read-only timeline UI: today's stats, anomaly flags, recent sessions, per-session detail with chain-integrity check.
+- **`dashcam brief`** — optional BYOK narration: your own API key (OpenAI-compatible or Anthropic) turns the digest into a plain-English briefing. Off by default; only aggregate stats are ever sent.
+- **SIEM-ready** — `dashcam export --format hec` emits Splunk HEC events. dashcam is the edge sensor; your SIEM stays the system of record. See [docs/SIEM.md](docs/SIEM.md).
+
+## What it is not
+
+- **Not a firewall.** dashcam never blocks, prompts, or restrains your agent. Blocking sidecars get bypassed by the agent, fatigue the user, and get uninstalled — we chose the other side of that trade on purpose. The tape doesn't lie, and it doesn't nag.
+- **Not a cloud service.** No accounts, no servers, no telemetry. Receipts live in `~/.dashcam/receipts.db`.
+
+## Already have Splunk?
+
+Then you know the gap: your SIEM sees EDR process events and proxy logs — *that something ran* — but not the agent's tool-call sequence. dashcam records the tape where the work happens (free, zero-config) and forwards clean JSONL to HEC when you're ready:
+
+```bash
+dashcam export --format hec | curl -H "Authorization: Splunk $HEC_TOKEN" \
+  --data-binary @- https://your-splunk:8088/services/collector/event
+```
+
+Regulators are asking for exactly this artifact: the EU AI Act (Art. 12, enforceable since Aug 2026) requires high-risk AI systems to keep **tamper-evident** event logs; SOC 2 and ISO 42001 demand the same discipline. dashcam produces the receipt; your SIEM keeps it. Full mapping in [docs/SIEM.md](docs/SIEM.md).
+
+## Quickstart
+
+```bash
+pipx install dashcam-ai        # or: pip install dashcam-ai
+dashcam demo               # 60-second tour on a scratch DB — your receipts stay clean
+dashcam ingest             # read all your agents' session logs (read-only, resumable)
+dashcam today              # what did my agents do today? (+ unusual-session flags)
+dashcam serve              # localhost timeline UI at http://127.0.0.1:8321
+dashcam brief              # BYOK plain-English briefing (needs your API key)
+dashcam runs               # sessions with tool calls, tokens and cost each
+dashcam verify             # prove the receipts weren't tampered with
+dashcam export --format bundle --session <id>  # signed receipt for auditors
+dashcam export             # dump receipts as JSON (or --format hec for Splunk)
+```
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["Agent transcripts<br/>Claude Code · Codex · Gemini · opencode"] -->|"read-only parse<br/>(nothing is modified)"| B["dashcam ingest"]
+    B -->|"hash-chained,<br/>one ACID txn per file"| C[("SQLite<br/>~/.dashcam/receipts.db")]
+    C --> D["today · brief<br/>(digest + anomaly flags)"]
+    C --> E["serve<br/>(localhost UI)"]
+    C --> F["verify<br/>(chain check)"]
+    C --> G["export --format hec"]
+    G --> H["Splunk / SIEM"]
+    C --> I["export --format bundle"]
+    I --> J["Signed receipt<br/>(auditors, clients)"]
+```
+
+Each recorded row seals the previous one into a SHA-256 chain. Delete or alter a row and `dashcam verify` fails — the same tamper-evidence idea behind signed audit logs, running entirely on your laptop. Details in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Security
+
+Full threat model in [SECURITY.md](SECURITY.md). The short version:
+
+- **Tamper-evident, not tamper-proof** — stated honestly, with the upgrade path documented.
+- **Secret redaction** — command text is scrubbed for recognizable secrets before persistence; full prompts are never stored.
+- **Local-first** — receipts never leave your machine. The only network calls dashcam ever makes are the ones you explicitly opt into: `brief` with your own API key. No telemetry, ever. DB is `0600`, directory `0700`.
+- **Crash-safe** — per-file ingestion is one ACID transaction; concurrent writers can't fork the chain (WAL + `BEGIN IMMEDIATE`).
+
+## Cost data
+
+Prices live in [`src/dashcam/data/models.json`](src/dashcam/data/models.json) (USD per 1M tokens). Providers change prices; when they do, send a PR that touches *only* that file. If the table is stale, drop your own `~/.dashcam/pricing.json` (same format) — it overrides the packaged table without a reinstall.
+
+## Roadmap
+
+- **v0.1** — the tape: Claude Code transcripts, hash-chained receipts, cost, digest, demo, verify, SIEM export
+- **v0.2** — universal tape: Codex CLI + Gemini CLI parsers, unusual-session flags, Ed25519 signed bundles
+- **v0.3** — opencode parser (SQLite), `dashcam serve` localhost timeline UI, `dashcam today --project`
+- **v0.4** — `dashcam brief`: optional BYOK narration (your key, off by default, aggregates only)
+
+The roadmap is complete. What's next is driven by real usage — file an issue with
+what your agents do that dashcam doesn't capture yet. See [docs/ROADMAP.md](docs/ROADMAP.md).
+
+## Honest comparisons
+
+- **vs. blocking sidecars** (pre-execution firewalls): they restrain, we record. Restraint gets bypassed by a capable agent and fatigues users; recording stays out of the agent's way and never nags. Different jobs. (Honest scope note: we only see what the harness actually writes to its logs.)
+- **vs. session scorers** (e.g. `agent-dashcam`): they grade your agent's *quality*; we keep the *evidence*. The tape comes before the verdict.
+- **vs. agentmetry** (closest in spirit — local-first flight recorder, hash-chained): they go wider (MITRE mapping, detections, DLP, blocking modes) via IDE hooks; we stay narrow (receipts + cost + digest) and read-only — no hooks to install, none to bypass. Early days for both; pick the philosophy you want.
+
+## Contributing
+
+PRs welcome. The bar: deterministic, read-only, tested. Every parser change needs fixture transcripts in `tests/`; price updates touch only the pricing file. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

dashcam_ai-0.4.0/SECURITY.md

@@ -0,0 +1,65 @@
+# Security policy
+
+## What dashcam is
+
+A read-only, local-first flight recorder. It parses the session logs your
+coding agents already write, keeps hash-chained receipts in SQLite, and
+never sends anything anywhere. There is no network code in this project —
+no telemetry, no accounts, no cloud sync, no update checks.
+
+## Threat model
+
+**In scope:**
+
+- *Post-hoc tampering with receipts.* Every evidentiary row (tool call,
+  spend) is sealed into a SHA-256 hash chain in global insertion order.
+  `dashcam verify` recomputes the chain; altering or deleting a row breaks
+  it. This catches accidental corruption (crashes, bit rot, partial
+  writes) and unsophisticated tampering.
+- *Secret leakage into receipts.* Command text and tool inputs pass
+  through deterministic redaction (`src/dashcam/redact.py`) before they
+  are persisted, and text is truncated. Full prompts are never stored.
+- *Local file exposure.* The database directory is created `0700` and the
+  database `0600` (POSIX). Receipts can contain command text — they are
+  not world-readable.
+- *Concurrent writers.* SQLite WAL mode, `BEGIN IMMEDIATE` around every
+  read-modify-write (so two processes can't fork the chain), a re-entrant
+  lock for threads, 30s busy timeout. Per-file ingestion runs inside one
+  ACID transaction: a crash mid-file rolls back instead of leaving half a
+  transcript.
+
+**Out of scope — stated plainly:**
+
+- The chain is **tamper-evident, not tamper-proof**. It is not keyed: an
+  attacker with unrestricted write access to `receipts.db` *and* the
+  knowledge to recompute the chain could forge a valid-looking history.
+  What the chain guarantees is *detection* of any modification by parties
+  who can't or don't rebuild it, plus all accidental corruption. If you
+  need proof against a fully-privileged local attacker, keep independent
+  copies of the database (backups detect divergence) — and see the
+  roadmap note on keyed receipts below.
+- dashcam does not sandbox, block, or restrain your agents. It is a
+  recorder. A compromised agent is outside this project's scope to stop;
+  the point is that the tape survives to show what happened.
+- Redaction is best-effort pattern matching, not a guarantee. Exotic
+  secret formats will slip through. Treat receipts as sensitive and keep
+  the `0600` permissions intact.
+
+**Roadmap (not yet built):** keyed receipts — HMAC-SHA256 with the key
+held in the OS keychain, so forging the chain requires keychain access
+too. This is the honest upgrade path from tamper-evident to tamper-proof.
+
+## Reporting a vulnerability
+
+Open a GitHub issue titled `[security]` with the details. Do not include
+secrets, tokens, or private data in the report. This is a young project;
+response time is best-effort but reports are taken seriously.
+
+## For contributors
+
+- Parsers must be read-only: never modify the harness logs.
+- Never persist full prompts, and run new tool-input shapes through
+  `redact()` — add a test in `tests/` proving the secret doesn't land in
+  the database.
+- Don't weaken file permissions, WAL mode, or the transaction discipline
+  in `store.py` without discussion in the PR.

dashcam_ai-0.4.0/docs/ARCHITECTURE.md

@@ -0,0 +1,120 @@
+# Architecture
+
+```
+harness logs (read-only)          local receipt store           outputs
+────────────────────────          ───────────────────           ───────
+~/.claude/projects/*/*.jsonl
+~/.codex/sessions/**/*.jsonl  ──┐
+~/.gemini/tmp/**/chats/*.{json,jsonl} │
+        │  parsers (ingest/)      │   SQLite, hash-chained
+        │  resume via file offsets│   ┌──────────────┐
+        ▼                         │  │ events, spend │──► dashcam today (digest + anomaly flags)
+  dashcam ingest ──atomic/file──► │  │ sessions      │──► dashcam runs
+                                  │  │ meta (offsets,│──► dashcam verify
+                                  │  │  chain head)  │──► dashcam export (JSON / HEC / signed bundle)
+                                  └──────────────┘         └──► dashcam verify-bundle (offline)
+```
+
+## The chain
+
+Each evidentiary row seals the previous one:
+
+```
+hash_n = sha256(hash_{n-1} + canonical_json({kind, seq, ...payload}))
+```
+
+- `seq` is a global monotonic counter across *both* tables, so verify
+  recomputes rows in exactly the order they were sealed — interleaved
+  event/spend writes verify correctly.
+- `canonical_json` is `json.dumps(sort_keys=True, separators=(",",":"))`.
+- Genesis is 64 zeroes. The head hash and seq live in `meta`.
+- `verify()` recomputes every row and compares both the per-row hash and
+  the stored head. Any modification or deletion is detected.
+
+`sessions` is index metadata (id, harness, project, timestamps) and is
+not chained; the *evidence* — what the agent did and what it cost — is.
+
+## Ingestion
+
+- Parsers translate one harness's log format into normalized
+  `Session` / `ToolEvent` / `Spend` records. See `ingest/base.py`.
+- Resume: per-file line offsets are stored in `meta` (`file:<path>`), so
+  re-running `ingest` only reads new lines. Sessions are idempotent
+  (`INSERT OR IGNORE` + offset tracking); re-ingestion never duplicates.
+- Malformed lines are skipped, never fatal. A parser must be total.
+- Each file's writes happen inside `Store.atomic()`: one ACID
+  transaction per file.
+- Summaries are truncated and passed through `redact()` before storage.
+
+## Cost
+
+`src/dashcam/data/models.json` maps `provider/model` → USD per 1M input/output
+tokens. Cost is computed at ingest from transcript token counts — no
+model calls, no proxy. Unknown models record `$0` and warn; price updates
+are data-only PRs touching just that file.
+
+## Adding a harness parser
+
+1. Read `ingest/base.py` — implement `HARNESS`, `iter_transcripts`,
+   `parse_transcript`.
+2. **Verify the format against real harness output.** A parser whose
+   format can't be confirmed against the actual harness does not ship:
+   wrong receipts are worse than missing ones.
+3. Add fixtures under `tests/fixtures/<harness>/` copied from real
+   (sanitized) logs, and tests covering: parsing, malformed lines,
+   incremental resume, dedup on re-ingest.
+4. Register it in `cli.PARSERS`.
+
+## Concurrency
+
+WAL mode + `BEGIN IMMEDIATE` on every read-modify-write + re-entrant
+thread lock + 30s busy timeout. Two `dashcam ingest` processes (or two
+agents' harnesses writing logs while dashcam reads) don't corrupt the
+store and can't fork the chain.
+
+## What this is not
+
+No firewall, no blocking, no prompt-injection judge, no network. The
+narrowness is the design: every feature must keep the receipt layer
+trustworthy, or it doesn't ship.
+
+## Anomaly surfacing (`anomaly.py`)
+
+Explainable statistics, no ML. For each (project, harness) pair, the
+trailing-30-day median per-session cost and tool-call count form the
+baseline (median is robust to the outliers being hunted). A session is
+flagged when it exceeds 3x the median on cost (floor: $1) or tool calls
+(floor: 10), and only when at least 5 baseline sessions exist — so new
+projects don't cry wolf. `dashcam today` shows the flags with the
+baseline numbers that triggered them.
+
+## Signed bundles (`signing.py`)
+
+The hash chain proves the local DB wasn't altered in place, but it can't
+leave the machine. `dashcam init` creates a local Ed25519 keypair
+(`~/.dashcam/signing.key`, mode 0600). `export --format bundle --session
+<id>` emits the session's canonical receipts plus signature and public
+key; `verify-bundle` checks the signature offline with no database
+access. This proves *provenance* — these receipts came from this dashcam
+identity, unaltered since signing — not protection against an attacker
+who owned the machine before signing. Keep offline copies of bundles
+for that threat.
+
+## Local UI (`serve.py`)
+
+`dashcam serve` renders a read-only timeline over the receipts with stdlib
+`http.server` only — no frameworks, no JavaScript. It binds 127.0.0.1,
+answers GET, and 405s everything else; user-controlled strings are
+HTML-escaped at render time. `/` shows today's cards, anomaly flags,
+recent sessions, and cost by harness; `/session?id=` shows tool calls,
+spend, and a per-session chain-link check (`dashcam verify` remains the
+full-chain authority).
+
+## BYOK narration (`brief.py`)
+
+`dashcam brief` is the only network-calling feature, and it's off unless
+you configure a key (`DASHCAM_API_KEY` or `~/.dashcam/llm.json`, 0600).
+It sends the *aggregate* digest text — counts, costs, top tools, anomaly
+flags — never raw summaries or prompt text, to an OpenAI-compatible or
+Anthropic endpoint over stdlib `urllib`. The system prompt forbids
+inventing numbers. Receipts stay the source of truth; the model narrates.

dashcam_ai-0.4.0/docs/ROADMAP.md

@@ -0,0 +1,42 @@
+# dashcam roadmap
+
+Principle: **depth on the core thesis** — the universal, intelligent,
+undeniable tape. A feature ships only if it makes the receipts more
+universal, more intelligent, or more portable.
+
+## v0.1 — the tape (shipped)
+- Claude Code transcript ingestion (read-only, resumable)
+- Hash-chained SQLite receipts + `dashcam verify`
+- Cross-provider cost from `src/dashcam/data/models.json`
+- `dashcam today` digest, `dashcam runs`, `dashcam demo`
+- Splunk HEC export (`docs/SIEM.md`)
+- CI (ruff + pytest on 3.10–3.13), PyPI trusted publishing with Sigstore attestations
+
+## v0.2 — universal tape (shipped)
+- Codex CLI + Gemini CLI parsers (verified against documented formats);
+  `dashcam ingest` reads all harnesses, `--harness` selects one
+- Unusual-session flags in `dashcam today` (median-baseline anomaly surfacing)
+- Ed25519 signed bundles: `export --format bundle` + `verify-bundle`
+  (offline-verifiable receipts for auditors)
+
+## v0.3 — more harnesses, more surface (shipped)
+- opencode session parser (SQLite source, read-only, fork-deduped)
+- `dashcam serve`: localhost-only read-only timeline UI (stdlib only)
+- Per-project digests (`dashcam today --project foo`)
+
+## v0.4 — optional brains (shipped, all off by default)
+- `dashcam brief`: BYOK narration of the digest via your own key
+  (OpenAI-compatible or Anthropic, stdlib HTTP). Deterministic receipts
+  stay the source of truth; the model only narrates. Only aggregate
+  stats are ever sent — never prompts or tool output.
+
+## What's next
+
+The planned roadmap is complete. Further work is driven by real usage:
+file an issue describing what your agents do that dashcam doesn't
+capture yet.
+
+## Non-goals (will not build)
+- Pre-execution blocking / firewalls — bypassable, fatiguing, uninstall-bait
+- Cloud sync, accounts, telemetry of any kind
+- LLM-as-judge verdicts on agent behavior — evidence in, verdicts out