argus-code 0.4.3__tar.gz → 0.4.4__tar.gz

argus_code-0.4.4/AGENTS.md

@@ -0,0 +1,119 @@
+# AGENTS.md — Argus (argus-code) root work contract
+
+> This repository uses the **DOX framework**: AGENTS.md files are binding work
+> contracts for their subtree. Before editing any path, read this file and every
+> AGENTS.md on the route from the repo root down to that path. The nearest doc
+> controls local detail; this root controls repo-wide rules. No child doc may
+> weaken DOX. Re-read the chain in-session; do not rely on memory.
+>
+> **After a meaningful change, run the DOX pass:** update the nearest owning
+> AGENTS.md (and any affected parent/child index) when you change purpose, scope,
+> contracts, workflows, inputs/outputs, or the doc tree itself; delete stale text;
+> then re-check changed paths against the chain. Pure no-behavior edits may leave
+> docs unchanged, but the pass still happens.
+
+## Purpose
+
+Argus is a **local-first** analytics dashboard for Claude Code (and other coding
+agents). A watcher ingests Claude Code's `.jsonl` session transcripts into a local
+SQLite archive (`~/.argus/argus.db`); a FastAPI server serves a static Astro
+dashboard at `http://localhost:4242`. No network, no telemetry, no LLM calls
+(except opt-in `argus pricing refresh`). Backend + dashboard ship together in the
+`argus-code` wheel on PyPI.
+
+Orientation docs (prose, not contracts — read but don't duplicate into AGENTS.md):
+- `ARCHITECTURE.md` — how the pieces fit together (read before adding a feature).
+- `CONTRIBUTING.md` — dev quick start (`uv sync`, `uv run argus start`).
+- `TESTING.md` — test catalog and conventions.
+
+## Ownership
+
+This root owns: the development workflow below, global engineering rules, the
+release process, and the top-level Child DOX Index. Code-level contracts live in
+the nearest child AGENTS.md.
+
+## Local Contracts
+
+### Development workflow (feature / bug → PR → merge → release → tag → publish)
+
+Follow this end-to-end for every feature or bug fix.
+
+1. **Branch.** Never commit feature/bug work directly to `main`. Branch from an
+   up-to-date `main`: `fix/<slug>` for bugs, `feat/<slug>` for features.
+2. **Implement test-first.** Reproduce the bug (or specify the feature) with a
+   failing test, then make it pass. See `tests/AGENTS.md`.
+3. **Commit** in small, logical units. Conventional-commit subjects
+   (`fix:`, `feat:`, `test:`, `release:`, `docs:`). End every commit message with:
+   ```
+   Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
+   ```
+4. **Verify** before opening the PR — see Verification below. Tests must be green
+   (the one known Windows flake is the scheduler timing test; confirm it passes in
+   isolation).
+5. **Push & open PR** against `main`: `gh pr create --base main --head <branch>`.
+   End the PR body with:
+   ```
+   🤖 Generated with [Claude Code](https://claude.com/claude-code)
+   ```
+6. **Merge** with squash and delete the branch:
+   `gh pr merge <n> --squash --delete-branch`. Then sync local `main`.
+7. **Release** (only when cutting a version — see Release process below).
+8. **Tag + GitHub release:** `gh release create vX.Y.Z --target main --title vX.Y.Z --notes "..."`.
+9. **PyPI publish is the maintainer's manual step** — see Release process.
+
+### Release process (manual — no CI release, no stored credentials)
+
+When cutting version `X.Y.Z`:
+1. Bump the version in **both** files with the Edit tool (not PowerShell
+   `Set-Content` — it injects a BOM): `pyproject.toml` (`version = "X.Y.Z"`) and
+   `python/argus/__init__.py` (`__version__ = "X.Y.Z"`).
+2. `uv lock` to sync `uv.lock` to the new version.
+3. If the dashboard changed, rebuild and refresh the shipped copy — see
+   `dashboard/AGENTS.md`.
+4. Clean-build the artifacts: **`rm -rf dist && uv build`** (always clear `dist/`
+   first, or stale files get uploaded).
+5. Confirm the wheel ships the right version + dashboard before publishing.
+6. Tag + GitHub release (workflow step 8).
+7. **Publish to PyPI — maintainer only:** `uv publish --token pypi-<token>`. The
+   token is the maintainer's secret; **an agent must never run this or handle the
+   token.** Stop and hand off.
+
+## Work Guidance
+
+Global engineering rules (binding):
+- **Never destroy user data in `~/.argus/argus.db`.** Migrations must be
+  non-destructive, idempotent, and self-healing. See `python/argus/store/AGENTS.md`.
+- **No hacks to make a test pass.** Fix the real cause, or correct a stale test
+  expectation to match the real contract (and say so). This is a prod package used
+  by many; never hardcode a value just to go green.
+- **Backend runs from source** (`uv run argus start`) — no build step for Python.
+  Only the dashboard has a build step.
+- Plans/specs under `docs/superpowers/` are scratch and gitignored — do not commit them.
+
+## Verification
+
+- Backend: `uv run pytest` (must be green; ~290 tests, ~25s on Windows).
+- Dashboard: `cd dashboard && npm run build` (must succeed).
+- Built form smoke test: see `CONTRIBUTING.md` "Running the built form".
+
+## User Preferences
+
+- Releases are cut deliberately by the maintainer; agents prepare everything up to
+  (and including the GitHub tag/release when asked) but never run `uv publish`.
+- Prefer honest reporting over green-at-any-cost: surface flakes, skips, and
+  pre-existing failures explicitly.
+
+## Child DOX Index
+
+- `python/argus/AGENTS.md` — Python backend package; owns the subsystems without
+  their own doc (`core`, `daemon`, `detectors`, `pricing`, `scaffold`, `schema`)
+  and indexes the four below.
+  - `python/argus/store/AGENTS.md` — SQLite, migrations, repository; data-safety
+    and path-normalization contracts.
+  - `python/argus/collector/AGENTS.md` — ingest pipeline and the missing-data
+    backfill (incl. sub-agent segment re-read).
+  - `python/argus/adapters/AGENTS.md` — Claude Code adapter and transcript-segment
+    extraction; sub-agent file layout.
+  - `python/argus/server/AGENTS.md` — FastAPI routes, static serving, clean shutdown.
+- `dashboard/AGENTS.md` — Astro dashboard and the `dashboard-dist` ship chain.
+- `tests/AGENTS.md` — pytest conventions and platform quirks.

argus_code-0.4.4/CLAUDE.md

@@ -0,0 +1,14 @@
+# CLAUDE.md
+
+This repository uses the **DOX framework** — an `AGENTS.md` hierarchy of binding
+work contracts. `AGENTS.md` (repo root) is the source of truth, including the full
+development workflow (branch → PR → squash-merge → release → tag → publish).
+
+**Before editing any path:** read the root `AGENTS.md`, then every `AGENTS.md` on
+the route down to that path; the nearest doc controls local detail. **After a
+meaningful change:** run the DOX closeout (update the nearest owning doc and any
+affected parent/child indexes). Re-read the chain in-session — don't rely on memory.
+
+The root contract (imported in full below):
+
+@AGENTS.md

{argus_code-0.4.3 → argus_code-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-code
-Version: 0.4.3
+Version: 0.4.4
 Summary: Local-first dashboard for Claude Code cost, token, tool-usage, and full-text search analytics
 Project-URL: Homepage, https://github.com/KrishBhimani/argus-code
 Project-URL: Repository, https://github.com/KrishBhimani/argus-code.git

{argus_code-0.4.3 → argus_code-0.4.4}/SECURITY.md

@@ -33,8 +33,10 @@ Argus is built for one user, one machine. It assumes:
   before rendering in the dashboard, and never executed.
 - **Untrusted browsers visiting localhost.** Other webpages the user
   loads while Argus is running are not trusted. They cannot read
-  Argus data (Same-Origin Policy on responses) and cannot trigger
-  state changes (CSRF Origin check on POST).
+  Argus data (Same-Origin Policy on responses, backed by a loopback
+  `Host` allowlist so DNS rebinding can't turn a hostile domain into
+  a same-origin one) and cannot trigger state changes (CSRF Origin
+  check on POST).
 
 ## Defaults that matter
 
@@ -78,14 +80,23 @@ Things this codebase deliberately does to reduce attack surface:
   `escapeHtml()` before reaching `innerHTML`. The only HTML allowed
   through is `<mark>...</mark>` from FTS5 `snippet()`, applied via a
   separate `safeSnippet()` helper that escapes everything else.
-- `watchdog` does not follow symlinks by default. `discover_session_files`
-  additionally calls `Path.resolve(strict=True)` on each candidate
-  and rejects anything that doesn't canonicalise under the
-  `~/.claude/` tree.
+- `watchdog` does not follow symlinks by default. Every read additionally
+  goes through `ClaudeCodeAdapter.ingest_file`, which calls
+  `Path.resolve(strict=True)` and refuses anything that doesn't
+  canonicalise under the `~/.claude/` tree — symlink or NTFS junction.
+  The check sits at that single choke point (not at each caller) so
+  discovery, the watcher, and the sub-agent walk are all covered by
+  construction; `sub_agent_files_for` filters as well.
 - Per-tick read cap of 64 MiB on session JSONL and `history.jsonl`,
   so a runaway or hostile multi-GB file can't OOM the process.
 - CSRF Origin check on all non-GET API routes (FastAPI middleware in
   `python/argus/server/app.py`).
+- Loopback `Host` header allowlist on **every** route, static mount
+  included (`is_loopback_host` in `python/argus/server/app.py`). This is
+  what stops DNS rebinding: a page on `evil.com` that repoints its own
+  DNS at `127.0.0.1` still sends `Host: evil.com` and gets a 421, so it
+  never reaches the GET routes the Origin check deliberately exempts.
+  Skipped only under `--host 0.0.0.0`, which is already a warned opt-out.
 - No build hooks running on user machines. The wheel ships pure Python
   + bundled data (`dashboard-dist/`, `pricing/`, `templates/`).
   Installation runs no arbitrary code.
@@ -95,7 +106,11 @@ Things this codebase deliberately does to reduce attack surface:
 - `argus claude` scaffolding is a pure file copy — no templating,
   substitution, or code execution. It writes only to the path you hand
   `init` (created if absent) or under `~/.argus/templates/`, and never
-  overwrites an existing `CLAUDE.md`.
+  overwrites an existing `CLAUDE.md`. That containment is enforced, not
+  just intended: every destination must canonicalise under the target
+  directory, so a hostile repo shipping `.claude/` as a symlink or NTFS
+  junction can't redirect the write, and template names are validated as
+  plain directory names so `--template ../../x` can't escape the store.
 
 If you spot a regression on any of the above, that's a real bug and
 worth reporting.

argus_code-0.4.4/dashboard/AGENTS.md

@@ -0,0 +1,35 @@
+# AGENTS.md — dashboard (Astro frontend + ship chain)
+
+Parent: repo-root `AGENTS.md`. The statically-built UI served by `server/`.
+
+## Purpose
+
+Astro + ECharts dashboard. Source pages live in `src/pages/*.astro`
+(`session.astro`, `settings.astro`, `overview`, `timeline`, …) with shared
+scripts in `src/scripts/`.
+
+## Local Contracts
+
+- **Three "dist" directories — don't conflate them:**
+  - `dashboard/dist/` — raw Astro build output. **Gitignored.**
+  - `dashboard-dist/` (repo root) — the **tracked** copy that ships in the wheel
+    via `pyproject.toml` force-include (`"dashboard-dist" = "argus/dashboard-dist"`).
+  - `dist/` (repo root) — `uv build` output uploaded to PyPI. **Gitignored.**
+- **A dashboard source edit is invisible to the package until `dashboard-dist` is
+  refreshed and committed.** After changing anything under `dashboard/src/`:
+  ```sh
+  cd dashboard && npm run build && cd ..
+  git rm -r --quiet dashboard-dist && cp -r dashboard/dist dashboard-dist && git add -A dashboard-dist
+  ```
+  Commit the rebuilt `dashboard-dist` alongside the source change. Astro filenames
+  are content-hashed, so a real change shows as new `_astro/*.js|css` plus updated
+  `*/index.html` — verify the new asset (and absence of stale strings) in
+  `dashboard-dist` before committing.
+- Avoid em dashes / non-ASCII in strings that surface in the **terminal**
+  (CLI/console) — they mojibake on the Windows console. (UI text is fine.)
+
+## Verification
+
+`cd dashboard && npm run build` must succeed. After refreshing `dashboard-dist`,
+optionally confirm the wheel ships it (`rm -rf dist && uv build`, then inspect the
+`.whl`).

{argus_code-0.4.3 → argus_code-0.4.4}/dashboard/src/pages/tools.astro

@@ -72,7 +72,11 @@ import Default from '../layouts/Default.astro';
             const i = p[0].dataIndex;
             const calls = values[i];
             const err = errors?.[i] ?? 0;
-            return `${labels[i]}<br>Calls: ${calls.toLocaleString()}` +
+            // ECharts renders a custom tooltip formatter's return value as
+            // HTML, so the label -- a tool / MCP-server / sub-agent name read
+            // verbatim from .jsonl -- must be escaped here too, exactly like
+            // every other innerHTML sink on this page.
+            return `${escapeHtml(labels[i])}<br>Calls: ${calls.toLocaleString()}` +
               (err ? `<br>Errors: ${err.toLocaleString()} (${((err/calls)*100).toFixed(1)}%)` : '');
           },
         },

argus_code-0.4.4/dashboard-dist/_astro/tools.astro_astro_type_script_index_0_lang.DHTUv2RL.js

@@ -0,0 +1,12 @@
+import{a as C,n,e as u}from"./format.BexCUztC.js";import{u as S,i as L,a as k,b as M,c as T,d as z,e as E}from"./installCanvasRenderer.XK5yP7fW.js";S([L,k,M,T,z]);const a=e=>document.querySelector(e),f=a("#w");let $,g,w;function h(e,t,o,l,c){const i=E(e);return i.setOption({textStyle:{color:"#9ba6b3"},tooltip:{trigger:"axis",axisPointer:{type:"shadow"},backgroundColor:"#1c222d",borderColor:"#262d3a",textStyle:{color:"#e6edf3",fontSize:12},formatter:d=>{const p=d[0].dataIndex,b=o[p],r=c?.[p]??0;return`${u(t[p])}<br>Calls: ${b.toLocaleString()}`+(r?`<br>Errors: ${r.toLocaleString()} (${(r/b*100).toFixed(1)}%)`:"")}},grid:{left:160,right:30,top:8,bottom:28},xAxis:{type:"value",axisLabel:{color:"#6b7585",fontSize:11},splitLine:{lineStyle:{color:"#1c222d"}},axisLine:{show:!1}},yAxis:{type:"category",data:t.slice().reverse(),axisLabel:{color:"#6b7585",fontSize:11},axisLine:{show:!1},axisTick:{show:!1}},series:[{type:"bar",data:o.slice().reverse(),itemStyle:{color:l,borderRadius:[0,4,4,0]},barWidth:"60%"}]}),i}function v(e,t,o,l="scalar"){const c=l==="name"?"font-size:1.05rem;font-family:'SF Mono',Consolas,monospace;font-weight:500;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;max-width:100%;display:block;color:var(--text-0);":"",i=l==="name"?`title="${t.replace(/"/g,"&quot;")}"`:"";return`<div class="card"><div class="kpi">
+        <div class="kpi-label">${e}</div>
+        <div class="kpi-value" style="${c}" ${i}>${t}</div>
+        ${o?`<div class="kpi-sub">${o}</div>`:""}
+      </div></div>`}async function x(){const e=await C.toolsOverview(f.value),t=e.total_calls,o=e.total_errors,l=t>0?(o/t*100).toFixed(1)+"%":"—",c=e.tool_leaderboard[0]?.name??"—",i=e.mcp_servers[0]?.server??"—";if(a("#kpis").innerHTML=[v("Tool calls",n(t),f.value==="all"?"all time":f.value),v("Error rate",l,o>0?`${n(o)} errors`:"no errors"),v("Top tool",u(c),e.tool_leaderboard[0]?`${n(e.tool_leaderboard[0].calls)} calls`:"","name"),v("Top MCP",u(i),e.mcp_servers[0]?`${n(e.mcp_servers[0].calls)} calls`:"no MCP usage","name")].join(""),$?.dispose(),e.tool_leaderboard.length===0)a("#leaderboard").innerHTML='<p class="empty">No tool activity in this window.</p>';else{const s=e.tool_leaderboard.slice(0,12);$=h(a("#leaderboard"),s.map(m=>m.name),s.map(m=>m.calls),"#f0883e",s.map(m=>m.errors))}const d=a("#splits"),p=d.children[0],b=d.children[1],r=e.mcp_servers.length>0,y=e.subagents.length>0;g?.dispose(),w?.dispose(),d.style.display=r||y?"":"none",p.style.display=r?"":"none",b.style.display=y?"":"none",r&&(g=h(a("#mcp"),e.mcp_servers.map(s=>s.server),e.mcp_servers.map(s=>s.calls),"#58a6ff",e.mcp_servers.map(s=>s.errors))),y&&(w=h(a("#subagents"),e.subagents.map(s=>s.type),e.subagents.map(s=>s.calls),"#bc8cff",e.subagents.map(s=>s.errors)));const _=a("#tools-table tbody");_.innerHTML=e.tool_leaderboard.length===0?'<tr><td colspan="4" class="empty">—</td></tr>':e.tool_leaderboard.map(s=>`
+          <tr>
+            <td><code>${u(s.name)}</code></td>
+            <td class="num">${n(s.calls)}</td>
+            <td class="num">${n(s.errors)}</td>
+            <td class="num">${(s.error_rate*100).toFixed(1)}%</td>
+          </tr>
+        `).join("")}f.addEventListener("change",x);x();window.addEventListener("resize",()=>[$,g,w].forEach(e=>e?.resize()));

{argus_code-0.4.3 → argus_code-0.4.4}/dashboard-dist/tools/index.html

@@ -1 +1 @@
-<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Argus — Tools</title><link rel="stylesheet" href="/styles/global.css"></head> <body> <header class="app-header"> <a href="/" class="brand">ARGUS<span class="dot">●</span></a> <nav class="app-nav"> <a href="/" class>Overview</a> <a href="/sessions" class>Sessions</a> <a href="/tools" class>Tools</a> <a href="/prompts" class>Prompts</a> <a href="/trends" class>Trends</a> <a href="/models" class>Models</a> <a href="/settings" class>Settings</a> </nav> </header> <main> <h2>Tool usage</h2> <div class="card" style="margin-bottom:1rem;display:flex;gap:0.6rem;align-items:center;"> <label style="color:var(--text-2);font-size:0.8rem;">Window</label> <select id="w"> <option value="today">Today</option> <option value="7d" selected>Last 7 days</option> <option value="30d">Last 30 days</option> <option value="all">All time</option> </select> </div> <div class="grid-cards" id="kpis"></div> <div class="card" style="margin-top:1.2rem;"> <h3>Tool leaderboard</h3> <div id="leaderboard" class="chart-tall"></div> </div> <div class="grid-2" style="margin-top:1.2rem;" id="splits"> <div class="card"> <h3>MCP servers</h3> <div id="mcp" class="chart"></div> </div> <div class="card"> <h3>Sub-agent invocations</h3> <div id="subagents" class="chart"></div> </div> </div> <div class="card" style="margin-top:1.2rem;"> <h3>Per-tool details</h3> <table id="tools-table"> <thead> <tr> <th>Tool</th> <th class="num">Calls</th> <th class="num">Errors</th> <th class="num">Error rate</th> </tr> </thead> <tbody></tbody> </table> </div> <script type="module" src="/_astro/tools.astro_astro_type_script_index_0_lang.OvyHH6MH.js"></script> </main> <footer class="app-footer" id="footer"> <span class="status-pill" id="ingest-status">Loading…</span> <span style="margin: 0 0.8rem;">·</span> <span id="pricing-info">Pricing —</span> <span id="daemon-status" style="margin-left: 0.8rem; display: none;" title="Ingestion is handled by the argusd background daemon">· Powered by argusd ●</span> </footer> <script type="module">async function c(){try{const[n,e]=await Promise.all([fetch("/api/pricing").then(s=>s.json()),fetch("/api/ingest/status").then(s=>s.json())]),o=document.getElementById("pricing-info");o&&(o.innerHTML=`Costs estimated from pricing table v<code>${n.version}</code> — tokens are exact; <code>argus pricing refresh</code> to update`);const t=document.getElementById("ingest-status");if(t)if(e.foregroundComplete&&e.pending===0){const s=typeof e.sessionCount=="number"?e.sessionCount:e.processed;t.textContent=`Tracking ${s} sessions`,t.classList.remove("busy")}else e.foregroundComplete?(t.textContent=`Backfilling history... ${e.processed}/${e.total}`,t.classList.add("busy")):(t.textContent=`Ingesting recent... ${e.processed}/${e.total}`,t.classList.add("busy"));const i=document.getElementById("daemon-status");i&&(i.style.display=e.daemon===!0?"inline":"none")}catch{}}c();setInterval(c,4e3);</script> </body> </html>
+<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Argus — Tools</title><link rel="stylesheet" href="/styles/global.css"></head> <body> <header class="app-header"> <a href="/" class="brand">ARGUS<span class="dot">●</span></a> <nav class="app-nav"> <a href="/" class>Overview</a> <a href="/sessions" class>Sessions</a> <a href="/tools" class>Tools</a> <a href="/prompts" class>Prompts</a> <a href="/trends" class>Trends</a> <a href="/models" class>Models</a> <a href="/settings" class>Settings</a> </nav> </header> <main> <h2>Tool usage</h2> <div class="card" style="margin-bottom:1rem;display:flex;gap:0.6rem;align-items:center;"> <label style="color:var(--text-2);font-size:0.8rem;">Window</label> <select id="w"> <option value="today">Today</option> <option value="7d" selected>Last 7 days</option> <option value="30d">Last 30 days</option> <option value="all">All time</option> </select> </div> <div class="grid-cards" id="kpis"></div> <div class="card" style="margin-top:1.2rem;"> <h3>Tool leaderboard</h3> <div id="leaderboard" class="chart-tall"></div> </div> <div class="grid-2" style="margin-top:1.2rem;" id="splits"> <div class="card"> <h3>MCP servers</h3> <div id="mcp" class="chart"></div> </div> <div class="card"> <h3>Sub-agent invocations</h3> <div id="subagents" class="chart"></div> </div> </div> <div class="card" style="margin-top:1.2rem;"> <h3>Per-tool details</h3> <table id="tools-table"> <thead> <tr> <th>Tool</th> <th class="num">Calls</th> <th class="num">Errors</th> <th class="num">Error rate</th> </tr> </thead> <tbody></tbody> </table> </div> <script type="module" src="/_astro/tools.astro_astro_type_script_index_0_lang.DHTUv2RL.js"></script> </main> <footer class="app-footer" id="footer"> <span class="status-pill" id="ingest-status">Loading…</span> <span style="margin: 0 0.8rem;">·</span> <span id="pricing-info">Pricing —</span> <span id="daemon-status" style="margin-left: 0.8rem; display: none;" title="Ingestion is handled by the argusd background daemon">· Powered by argusd ●</span> </footer> <script type="module">async function c(){try{const[n,e]=await Promise.all([fetch("/api/pricing").then(s=>s.json()),fetch("/api/ingest/status").then(s=>s.json())]),o=document.getElementById("pricing-info");o&&(o.innerHTML=`Costs estimated from pricing table v<code>${n.version}</code> — tokens are exact; <code>argus pricing refresh</code> to update`);const t=document.getElementById("ingest-status");if(t)if(e.foregroundComplete&&e.pending===0){const s=typeof e.sessionCount=="number"?e.sessionCount:e.processed;t.textContent=`Tracking ${s} sessions`,t.classList.remove("busy")}else e.foregroundComplete?(t.textContent=`Backfilling history... ${e.processed}/${e.total}`,t.classList.add("busy")):(t.textContent=`Ingesting recent... ${e.processed}/${e.total}`,t.classList.add("busy"));const i=document.getElementById("daemon-status");i&&(i.style.display=e.daemon===!0?"inline":"none")}catch{}}c();setInterval(c,4e3);</script> </body> </html>

{argus_code-0.4.3 → argus_code-0.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "argus-code"
-version = "0.4.3"
+version = "0.4.4"
 description = "Local-first dashboard for Claude Code cost, token, tool-usage, and full-text search analytics"
 readme = "README.md"
 requires-python = ">=3.11"

argus_code-0.4.4/python/argus/AGENTS.md

@@ -0,0 +1,50 @@
+# AGENTS.md — Python backend package (`argus`)
+
+Parent: repo-root `AGENTS.md`. Read it first for the workflow and global rules.
+
+## Purpose
+
+The `argus` package: ingest Claude Code transcripts, store them in SQLite, serve
+the dashboard, and provide the `argus` CLI. Runs directly from source
+(`uv run argus start`) — no build step. Entry point: `argus = "argus.cli:app"`.
+
+## Ownership
+
+This doc owns backend-wide rules and the subsystems that have no child doc:
+- `core/` — runtime wiring (`RuntimeOptions`, building the watcher + server).
+- `daemon/` — `argusd` background service: pidfile, process lifecycle, logging.
+- `detectors/` — alert detectors (registry + individual rules like tool-error-rate spike).
+- `pricing/` — pricing table load / refresh / compute; bundled JSON under repo `pricing/`.
+- `scaffold/` — `argus claude` scaffolding (templates, snapshot, storage).
+- `schema/` — shared pydantic types (`Session`, `Turn`, …). Changing a stored
+  field ripples into `store/` (columns) and `server/` (serialization).
+
+Delegated subtrees (see their own AGENTS.md): `store/`, `collector/`, `adapters/`, `server/`.
+
+## Local Contracts
+
+- **Version lives in two files** that must stay in lock-step: `__init__.py`
+  (`__version__`) and repo-root `pyproject.toml`. Bump both on release (root doc).
+- **CLI command groups** are Typer apps wired in `cli.py`. When renaming a
+  user-facing command, keep the old name as a `hidden=True` alias and nudge to the
+  new one (precedent: `search` → `indexing`). Update help strings, the daemon
+  read-only API hint, and dashboard copy together.
+- **Privacy stays intact:** no network calls or telemetry beyond opt-in
+  `argus pricing refresh`. Don't add outbound calls.
+
+## Work Guidance
+
+- Follow existing module patterns; keep files focused and small.
+- Python ≥ 3.11. Dependencies are deliberately minimal (fastapi, uvicorn,
+  pydantic, watchdog, typer, httpx) — don't add deps without cause.
+
+## Verification
+
+`uv run pytest` (full suite). Subsystem tests live under `tests/<subsystem>/`.
+
+## Child DOX Index
+
+- `store/AGENTS.md` — SQLite, migrations, repository; data-safety + path normalization.
+- `collector/AGENTS.md` — ingest pipeline and missing-data backfill.
+- `adapters/AGENTS.md` — Claude Code adapter and transcript-segment extraction.
+- `server/AGENTS.md` — FastAPI routes, static serving, clean shutdown.

{argus_code-0.4.3 → argus_code-0.4.4}/python/argus/__init__.py

@@ -1,3 +1,3 @@
 """Argus — local-first analytics for Claude Code and other coding agents."""
 
-__version__ = "0.4.3"
+__version__ = "0.4.4"

argus_code-0.4.4/python/argus/adapters/AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md — adapters (Claude Code transcript adapter)
+
+Parent: `python/argus/AGENTS.md`. Parses agent transcript files into typed results.
+
+## Purpose
+
+`claude_code/` reads Claude Code's `.jsonl` transcripts: `adapter.py` discovers and
+ingests files, `schemas.py` validates each line (`AssistantLine`, `UserLine`, …),
+`extract_transcript.py` derives searchable segments.
+
+## Local Contracts
+
+- **Discovery excludes sub-agent files.** `discover_session_files()` returns
+  top-level session files only; sub-agent transcripts are reached via
+  `sub_session_files_for(parent_file)`, which walks the parent's `subagents/`
+  directory (including the nested `subagents/workflows/<wf>/agent-*.jsonl` layout).
+- **Sub-agent session id** = `<parent_session_id>/<sub_file_stem>` (e.g.
+  `claude_code:<parent>/agent-<hex>`). The `/` is what marks a row as a sub-agent
+  everywhere downstream.
+- **`extract_transcript_segments`** emits `RawSegment`s with roles `assistant`,
+  `thinking`, `user`, and `tool_result`; each is byte-capped (`_cap_text`). The
+  first `user` segment of a sub-agent is its "Task given" in the dashboard.
+- **Known data limitation — do not design against it:** `subagent_type` is empty
+  for every row, sub-agent ids are exactly one level deep, and there is no stored
+  workflow grouping or spawn-turn link. Don't build features that assume a nested
+  sub-agent tree, type pills, or a spawn→child edge; the data isn't there.
+- **`ingest_file(path, offset)` is pure-ish:** it parses from a byte offset and
+  returns `(result, new_offset)`. It does not write to the DB — `collector/` owns
+  persistence and offset bookkeeping.
+- **Path containment is enforced at `ClaudeCodeAdapter.ingest_file`, and that is
+  deliberate.** It is the one choke point every read reaches — discovery, the
+  watcher's fs events, and the pipeline's sub-agent walk — so a path that doesn't
+  `resolve()` under the adapter's root gets an empty result and a logged warning
+  instead of being read. Don't move this check out to the callers: it lived only
+  in `discover_session_files()` once, and `sub_agent_files_for()` plus the watcher
+  silently bypassed it into an arbitrary-file-read (bytes reached `parse_errors`,
+  which `GET /api/parse-errors` serves out). `sub_agent_files_for()` now *also*
+  takes `claude_root` and filters — required, not optional, so a new caller must
+  confront it. Covers symlinks and NTFS junctions alike (both resolve out).
+
+## Verification
+
+`uv run pytest tests/adapters`. Real-`~/.claude/` tests are gated by
+`ARGUS_REAL_CLAUDE_ROOT` and skipped otherwise.

{argus_code-0.4.3 → argus_code-0.4.4}/python/argus/adapters/claude_code/adapter.py

@@ -1,19 +1,22 @@
 """The Claude Code adapter — façade that wires the package together."""
 from __future__ import annotations
 
+import logging
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 from ..base import AdapterIngestResult
 from ..registry import register
-from .discover import discover_session_files, sub_agent_files_for
+from .discover import _safe_realpath_under, discover_session_files, sub_agent_files_for
 from .history_jsonl import ingest_history_file
-from .ingest_file import ingest_claude_code_file
+from .ingest_file import _empty_result, ingest_claude_code_file
 from .model import canonicalize_claude_model
 
 if TYPE_CHECKING:
     from ...store.repository import Repository
 
+logger = logging.getLogger(__name__)
+
 
 def _default_root() -> Path:
     return Path.home() / ".claude"
@@ -38,6 +41,14 @@ class ClaudeCodeAdapter:
     def ingest_file(
         self, path: Path, from_offset: int = 0
     ) -> tuple[AdapterIngestResult, int]:
+        # Containment lives here, at the one choke point every read passes
+        # through -- discovery, the watcher's fs events, and the sub-agent
+        # walk in the pipeline all land on this method. Checking here rather
+        # than at each caller is what stops a future call site from quietly
+        # reopening the arbitrary-file-read hole (see discover.py's rules).
+        if _safe_realpath_under(path, self._root) is None:
+            logger.warning("refusing to ingest a path outside the claude root: %s", path)
+            return _empty_result(path), from_offset
         return ingest_claude_code_file(path, from_offset)
 
     # ─── Extension-point overrides ─────────────────────────────────────
@@ -52,7 +63,7 @@ class ClaudeCodeAdapter:
             ingest_history_file(path, repo)
 
     def sub_session_files_for(self, session_file: Path) -> list[Path]:
-        return sub_agent_files_for(session_file)
+        return sub_agent_files_for(session_file, self._root)
 
     def should_skip(self, path: Path) -> bool:
         # The subagents/ tree is walked as part of the parent's ingest,

{argus_code-0.4.3 → argus_code-0.4.4}/python/argus/adapters/claude_code/discover.py

@@ -66,7 +66,7 @@ def discover_session_files(claude_root: Path) -> list[Path]:
     return out
 
 
-def sub_agent_files_for(session_file: Path) -> list[Path]:
+def sub_agent_files_for(session_file: Path, claude_root: Path) -> list[Path]:
     """Return the sub-agent transcript JSONLs for a session.
 
     Two on-disk layouts coexist under ``<session_dir>/<sid>/subagents/``:
@@ -88,12 +88,25 @@ def sub_agent_files_for(session_file: Path) -> list[Path]:
     sub = session_file.parent / sid / "subagents"
     if not sub.exists():
         return []
+    try:
+        canonical_root = claude_root.resolve(strict=True)
+    except (OSError, RuntimeError):
+        return []
     out: set[Path] = set()
     # Flat transcripts directly under subagents/ (dirs like workflows/ have
     # no .jsonl suffix, so they're skipped here).
     out.update(f for f in sub.iterdir() if f.is_file() and f.suffix == ".jsonl")
     # Nested Workflow sub-agent transcripts, any depth below subagents/.
     out.update(f for f in sub.rglob("agent-*.jsonl") if f.is_file())
+    # Same containment rule as discover_session_files: a symlink planted in
+    # subagents/ must not turn into an arbitrary file read. (rglob does not
+    # follow directory symlinks, but a symlinked *file* still resolves out.)
+    dropped = {f for f in out if _safe_realpath_under(f, canonical_root) is None}
+    for f in sorted(dropped):
+        logger.warning(
+            "skipping sub-agent transcript that escapes the claude root: %s", f
+        )
+    out -= dropped
 
     if not out and any(c.is_dir() for c in sub.iterdir()):
         # subagents/ has subdirectories but nothing matched — the layout

{argus_code-0.4.3 → argus_code-0.4.4}/python/argus/cli.py

@@ -15,7 +15,11 @@ import argus.detectors  # noqa: F401  — triggers @register side-effects
 from .pricing.load import load_pricing_table
 from .pricing.refresh import diff_pricing, fetch_litellm_table
 from .scaffold.scaffolder import scaffold_project
-from .scaffold.snapshot import snapshot_candidates, snapshot_template
+from .scaffold.snapshot import (
+    secret_files_in,
+    snapshot_candidates,
+    snapshot_template,
+)
 from .scaffold.storage import RESERVED_TEMPLATE_NAMES, list_templates, resolve_template
 from .server.app import ServerOpts, build_app, serve_blocking
 from .store.db import open_db
@@ -288,6 +292,14 @@ def claude_init(
     """Scaffold a .claude/ setup (and CLAUDE.md) into a project."""
     try:
         template_dir = resolve_template(template, data_dir)
+    except ValueError:
+        # Path-like name (e.g. ../../x) — rejected before it touches the disk.
+        typer.echo(
+            f"Invalid template name '{template}'. "
+            "Use a plain name: letters, digits, dot, dash, underscore.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
     except KeyError:
         avail = ", ".join(list_templates(data_dir)) or "(none)"
         typer.echo(f"Unknown template '{template}'. Available: {avail}", err=True)
@@ -358,6 +370,17 @@ def template_create(
         typer.echo(str(e), err=True)
         raise typer.Exit(code=1)
     typer.echo(f"Created template '{name}' at {target}")
+    # Say what was withheld. A credential filter that drops files silently is
+    # its own bug — the user needs to know the template is deliberately
+    # incomplete, and why.
+    withheld = secret_files_in(project / ".claude")
+    if withheld:
+        typer.echo(
+            "\nLeft out of the template (looks like credentials): "
+            + ", ".join(withheld)
+            + "\nTemplates get copied into every project you scaffold, so "
+            "secrets are never snapshotted."
+        )
 
 
 @app.command()

argus_code-0.4.4/python/argus/collector/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md — collector (ingest pipeline + backfill)
+
+Parent: `python/argus/AGENTS.md`. Turns transcript files into stored rows.
+
+## Purpose
+
+`pipeline.py` ingests one file tick; `first_run.py` orchestrates the first-pass
+ingest (foreground recent files, background older files) and backfills derived data
+after a schema/feature upgrade.
+
+## Local Contracts
+
+- **Offset-driven reads.** `ingest_file` reads only bytes after the stored file
+  offset, upserts turns/tool_calls/segments, then recomputes the session. A
+  fully-read file sits at EOF and is **not** re-read on the next tick. To force a
+  re-extract you MUST reset its offset to 0 (`repo.set_file_offset(path, 0)`) —
+  re-calling `ingest_file` alone does nothing for an EOF file.
+- **Sub-agents are walked via the parent.** A parent ingest discovers
+  `adapter.sub_session_files_for(parent)` and ingests any that **grew past their
+  offset**. Sub-agent session ids contain `/` (`<parent>/agent-<hex>`).
+- **Segments are gated on indexing.** Parent and sub-agent segments are written
+  only when `repo.is_search_indexing_enabled()` (see `store/AGENTS.md`). So
+  enabling indexing *after* ingest requires re-reading the relevant files.
+- **Backfill (`_backfill_missing_derived_data`) routes through parents.** Ids with
+  `/` are skipped by the processing loop ("walked via parents"). Anything needing a
+  sub-agent file re-read must add the **parent** id to both the work set and
+  `deep_reset` (deep_reset zeroes the sub-agent file offsets). Missing-segment
+  sessions therefore map to their parent + deep_reset — otherwise sub-agent
+  segments never backfill and the dashboard's "Task given" stays empty.
+- **Bounded per run.** Backfill candidates are capped (200) per `argus start`;
+  large installs may need several restarts to converge. If you add a new bounded
+  sweep, surface what was deferred rather than silently truncating.
+
+## Verification
+
+`uv run pytest tests/collector` — covers incremental re-ingest, sub-agent
+backfill, segment gating, and the "enable indexing late" path.

{argus_code-0.4.3 → argus_code-0.4.4}/python/argus/daemon/process.py

@@ -20,6 +20,12 @@ from . import pidfile
 def daemon_argv(data_dir: Path) -> list[str]:
     return [
         sys.executable,
+        # -P (3.11+) keeps the *caller's* cwd off the child's sys.path. Without
+        # it, `-m` prepends cwd, so running `argus daemon start` from inside a
+        # checkout that ships its own `argus/` directory would run that code
+        # instead of the installed package -- arbitrary execution in a detached
+        # process that outlives the shell.
+        "-P",
         "-m",
         "argus.cli",
         "daemon",

{argus_code-0.4.3 → argus_code-0.4.4}/python/argus/scaffold/scaffolder.py

@@ -1,6 +1,7 @@
 """Copy a template directory into a project — the `argus claude init` core."""
 from __future__ import annotations
 
+import os
 import shutil
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -9,6 +10,25 @@ from pathlib import Path
 _CLAUDE_MD = "CLAUDE.md"
 
 
+def _resolves_inside(target: Path, root: Path) -> bool:
+    """True if ``target`` canonicalises to ``root`` or below it.
+
+    ``resolve()`` follows every symlink and NTFS junction on the path —
+    including the final component, and including a *dangling* link — which is
+    exactly what we need. ``shutil.copyfile`` writes *through* a symlink, and
+    the caller's ``target.exists()`` guard follows one too (so a dangling link
+    reports "doesn't exist" and then gets created on write). Comparing
+    canonical paths is the only check that catches all of those.
+    """
+    try:
+        resolved = target.resolve()
+    except (OSError, RuntimeError):
+        return False
+    a = os.path.normcase(str(resolved))
+    b = os.path.normcase(str(root))
+    return a == b or a.startswith(b + os.sep)
+
+
 @dataclass
 class ScaffoldResult:
     created: list[Path] = field(default_factory=list)
@@ -26,11 +46,20 @@ def scaffold_project(
     - ``CLAUDE.md`` is NEVER overwritten, even with ``force``.
     """
     result = ScaffoldResult()
+    dest_root = dest.resolve()
     for src in sorted(p for p in template_dir.rglob("*") if p.is_file()):
         rel = src.relative_to(template_dir)
         target = dest / rel
         is_claude_md = rel.as_posix() == _CLAUDE_MD
 
+        # Never write outside the destination. A hostile repo can ship
+        # `.claude/` as a symlink/junction, or `.claude/settings.json` as a
+        # link to ~/.ssh/authorized_keys; cloning it and running
+        # `argus claude init` would otherwise write through that link.
+        if not _resolves_inside(target, dest_root):
+            result.skipped.append((target, "would write outside the project"))
+            continue
+
         if target.exists():
             if is_claude_md:
                 result.skipped.append((target, "CLAUDE.md exists, left untouched"))