agentwrangler 0.1.0 → 0.1.1-next.2e8c141

package/README.md

@@ -1,116 +1,184 @@
-# AgentWrangler
+<p align="center">
+  <img src="docs/assets/logo.png" alt="AgentWrangler logo" width="260">
+</p>
 
-Local-first observability for Claude Code that **joins your token spend to the pull requests it
-actually merged or closed** — entirely on your machine — and ships **installable guardrails** (a
-dangerous-command block, a pre-compaction checkpoint, a context-budget warning) you turn on from the
-dashboard. See where your agent budget goes, whether the work shipped, and cut the waste.
+<h1 align="center">AgentWrangler</h1>
 
-## Local-only — your data never leaves your machine
+<p align="center">
+  <b>See where your Claude Code tokens go — and whether the work actually shipped.</b><br>
+  Local-first observability for Claude Code: token spend, session outcomes, waste detection,
+  and installable guardrails. Runs entirely on your machine.
+</p>
 
-AgentWrangler runs entirely on your computer: a daemon bound to **`127.0.0.1`** and a dashboard in
-your browser that talks only to that loopback address. **No cloud backend, no telemetry, nothing
-phones home.** It reads your local Claude Code transcripts, stores only aggregates in a local SQLite
-file (`~/.agentwrangler/db.sqlite`), and never persists raw transcript or PR content — only counts,
-ids, and structural anchors (the SEC-101 privacy invariant). An optional GitHub token, used only for
-the outcomes feature, is read locally, never logged, and never leaves your machine.
-
-**Privacy exception (opt-in):** `npm run evidence:judge-g2 -- --execute` is the only path where PR
-content leaves the machine. It calls the Claude API with your local Claude Code OAuth credential to
-adjudicate G2 deferral findings, and runs only when `g2_claude_judge_opt_in` is enabled; otherwise it
-refuses to run. No rationale text is persisted.
+<p align="center">
+  <a href="https://www.npmjs.com/package/agentwrangler"><img src="https://img.shields.io/npm/v/agentwrangler" alt="npm version"></a>
+  <a href="https://github.com/Doogit/AgentWrangler/actions/workflows/ci.yml"><img src="https://github.com/Doogit/AgentWrangler/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://img.shields.io/node/v/agentwrangler"><img src="https://img.shields.io/node/v/agentwrangler" alt="node version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="license"></a>
+</p>
 
 ![AgentWrangler dashboard — spend verdict, model mix, recommendations, and per-repo efficiency](docs/assets/dashboard.gif)
 
 <!--
-  Captured from a SANITIZED instance (Vite test-mode fixtures — anonymized names, no
-  live data) so no real workspace/repository names/paths are committed (SEC-101).
-  Regenerate with the ce-demo-reel skill against `npx vite --mode test`.
+  All screenshots and the demo GIF in this README are captured from a SANITIZED instance
+  (Vite test-mode fixtures — anonymized names, no live data) so no real workspace/repository
+  names or paths are committed (SEC-101). Regenerate against `npx vite --mode test`.
 -->
 
-## Quick start
+## Why
 
-Requirements: **Node `>=22 <25`** and npm.
+Claude Code tells you almost nothing about where your token budget goes. Sessions balloon,
+caches miss, background agents idle — and you find out when you hit the rate limit.
+AgentWrangler reads the transcripts Claude Code already writes to your disk and answers three
+questions:
 
-```sh
-git clone https://github.com/Doogit/AgentWrangler && cd AgentWrangler
-npm ci
-npm run build:ui       # build the dashboard
-npm run daemon         # starts the daemon and opens your browser
-```
+- **Where did the tokens go?** Per-model, per-workspace, per-session spend with cache economics.
+- **Did the work ship?** Sessions are linked to the pull requests they merged or closed.
+- **What should I change?** Ranked waste-source detectors with modeled savings — and one-click
+  guardrail hooks that warn *inside* Claude Code before waste happens.
 
-Then open **http://127.0.0.1:47821** (the daemon opens it for you unless `AW_NO_OPEN=1`).
+No cloud backend, no telemetry, no account. A daemon on `127.0.0.1`, a dashboard in your
+browser, and a SQLite file in your home directory.
 
-After installing dependencies you can also do it in one step:
+## Quick start
 
 ```sh
-npm ci                 # required first — the CLI runs via tsx, a devDependency
-npx agentwrangler      # builds the UI if needed, then launches the daemon + browser
+npx agentwrangler@latest
 ```
 
-On first launch the daemon binds the port immediately and serves a loading page, then scans your
-`~/.claude/projects/**/*.jsonl` transcripts in the background — the dashboard appears right away and
-fills in as the scan completes, so a large history won't block the page from opening.
+That's it — requires Node **22–24**. The daemon starts on `http://127.0.0.1:47821`, opens your
+browser, and scans your `~/.claude/projects` transcripts in the background; the dashboard
+appears immediately and fills in as the scan completes.
 
-## Optional setup
+More options (install from source, GitHub outcomes sync, environment variables):
+**[Getting started →](docs/getting-started.md)**
 
-- **GitHub outcomes sync** — links sessions to the PRs/commits they produced. Provide a read-only
-  GitHub PAT via the `AW_GITHUB_TOKEN` environment variable (works on all platforms). On Windows you
-  may instead store it in Credential Manager as `AgentWrangler-GithubToken`. Without a token the
-  outcomes feature stays inert and Settings tells you so — nothing fails silently.
-- **Usage reader** — reads your Claude Code OAuth credentials locally to calibrate the weekly limit
-  and burn forecast. Sign in through Claude Code as usual; Settings shows the reader status.
-- **Context-budget hook** — an optional PreToolUse hook that warns before long sessions balloon.
-  Install it from the Settings page (or `npm run install-hook`).
+## Features
 
-## Configuration (environment variables)
+### Overview — verdict first, details on demand
 
-All are optional; sensible defaults apply. See [`.env.example`](.env.example) for the full list.
+One screen answers "how bad is it this week": a spend verdict with trend, your top waste
+source with a copyable fix prompt, live rate-limit gauges (5-hour and 7-day), a burn forecast
+against your calibrated weekly limit, hot sessions, cache efficiency, and per-model
+context-per-turn tiles.
 
-| Variable | Purpose | Default |
-|---|---|---|
-| `AW_PORT` | Daemon HTTP port | `47821` |
-| `AW_DB_PATH` | SQLite database path | `~/.agentwrangler/db.sqlite` |
-| `AW_SCAN_ROOT` | Transcript corpus to scan | `~/.claude/projects` |
-| `AW_UI_ROOT` | Directory the built UI is served from | `<repo>/dist/ui` |
-| `AW_GITHUB_TOKEN` | Read-only GitHub PAT for outcomes sync | *(unset)* |
-| `AW_NO_OPEN` | Set to `1` to not auto-open the browser | *(unset)* |
+![Overview tab — at-a-glance verdict, rate limits, burn forecast, hot sessions](docs/assets/overview.png)
 
-## What it measures
+### Recommendations — waste-source detectors, ranked by impact
 
-AgentWrangler ingests your transcripts and surfaces cost trends, cache-efficiency, session hygiene
-findings (e.g. long sessions never `/clear`ed, limit-burn risk), and — with a GitHub token — outcome
-linkage between sessions and the work they shipped. Numbers are cap-weighted and honesty-tiered: the
-UI is explicit about what is measured versus estimated, and never invents a proxy it can't ground.
-Definitions live in [`docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md`](docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md).
+Ten detector families watch your sessions for the patterns that actually burn tokens: cache
+misses (the biggest single lever), session hygiene, retry/redundant-read loops, tool-result
+bloat, model routing, idle background sessions, and more. Each recommendation shows modeled
+weekly savings, a confidence tier, and a concrete action — install a hook, copy a config
+snippet, or copy a guided prompt straight into Claude Code. Adopted changes flow into an
+**impact ledger** that tracks the measured effect, and modeled savings are never counted as
+achieved.
 
-## Limitations
+![Recommendations tab — ranked detector families with modeled savings and one-click actions](docs/assets/recommendations.png)
 
-- **Platform support.** Tested on Windows; macOS/Linux are believed working — reports welcome.
-- **Transcript-format coupling.** AgentWrangler reads Claude Code's JSONL transcript format; a change
-  to that format upstream can require an ingestion update.
-- **Outcomes credential sources.** The cross-platform path is `AW_GITHUB_TOKEN`; the OS credential
-  store integration currently covers Windows Credential Manager only (macOS/Linux keychain is a
-  follow-on).
-- **Single local user.** It observes one machine's Claude Code history; there is no multi-user or
-  team-aggregation mode by design.
+### Installable guardrails — local checks inside Claude Code, before the waste
 
-## License
+Five small hooks you can install from the dashboard (directly, or via a copyable prompt that
+Claude Code applies itself):
+
+| Guardrail | What it does |
+|---|---|
+| **Context-budget warning** | Warns when a session's context crosses your soft/hard thresholds |
+| **Loop guard** | Flags repeated identical tool failures before they spiral |
+| **Burn alert** | Catches idle sessions still burning tokens in the background |
+| **Pre-compaction checkpoint** | Copies the raw local transcript before an automatic compaction, subject to a local retention cap |
+| **Dangerous-command guard** | Asks before risky shell commands and denies a small catastrophe list |
+
+The context-budget and burn hooks warn. The loop guard warns before it denies repeated identical
+failures, and the dangerous-command guard can ask or deny. Direct install enables all five hooks;
+the copied install prompt enables the context-budget, loop, and burn hooks only. Thresholds are
+tunable from Settings, and direct uninstall removes every AgentWrangler hook.
+
+### Sessions — who spent it, and on what
+
+The highest-cost sessions ranked with their output-to-context split, model, friction band
+(API errors, tool failures, compactions, interrupts), and a "top X% by spend" self-percentile
+chip. Drill into any session for a turn-by-turn timeline, its cost drivers (which detectors
+fired and how hard), and a guided fix prompt built only from measured numbers.
+
+![Sessions tab — highest-cost sessions with friction bands and spend percentiles](docs/assets/sessions.png)
+
+<details>
+<summary>Session detail view</summary>
+
+![Session detail — per-session KPIs, cost drivers, and a measured-context fix prompt](docs/assets/session-detail.png)
+</details>
+
+### Workspaces — spend efficiency by repository
+
+Every repo you run Claude Code in, with spend share, trend, context-per-turn, cache-write
+share, Opus share, and $/turn. With a GitHub token configured, sessions are linked to the PRs
+and commits they produced — so you can see cost-per-merged-PR, not just cost.
 
-Licensed under the [Apache License 2.0](LICENSE). Copyright 2026 AgentWrangler contributors.
+![Workspaces tab — per-repository spend, efficiency, and outcome linkage](docs/assets/workspaces.png)
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) to build and test, [SECURITY.md](SECURITY.md) to report a
-vulnerability, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+<details>
+<summary>Workspace detail view</summary>
 
-## Documentation index
+![Workspace detail — top sessions, context composition, and outcomes](docs/assets/workspace-detail.png)
+</details>
 
-| Path | Purpose |
+### Weekly brief — one page, three decisions
+
+The week in one screen: spend verdict, what changed vs. last week, the top actions to take —
+with a **Copy as Markdown** button so the whole brief drops into a standup note or a message.
+
+![Briefs tab — weekly verdict, week-over-week deltas, and top actions](docs/assets/briefs.png)
+
+### Honest numbers, labeled as such
+
+Every metric carries an honesty-tier chip — `EXACT`, `LIST_EQUIV`, `MODELED`, `PROXY`,
+`DIRECTIONAL`, `EXPERIMENTAL` — so you always know what is measured versus estimated. Dollar
+figures are list-price *equivalents* (subscription plans aren't billed per token; tokens drive
+rate limits), and the built-in glossary ("How to read this dashboard") defines every
+key metric in plain language. The full tour: **[Dashboard tour →](docs/dashboard-tour.md)**
+
+## Privacy — local-only by design
+
+- The daemon binds to **`127.0.0.1`** only. There is no cloud backend, telemetry, or account.
+- Most dashboard data is **aggregates, ids, counts, and structural anchors**. Local command text
+  and filesystem paths can also be retained in SQLite; treat the database as sensitive. The optional
+  direct-install PreCompact hook can separately copy full raw transcripts locally.
+- The optional GitHub token is read locally, never logged, never persisted to the DB.
+- Usage refreshes can call Anthropic with an existing Claude Code sign-in. GitHub outcomes sync
+  calls GitHub only when a token is configured; calibration and G2 judging are separate opt-ins.
+
+Full details, including exactly what is and isn't stored: **[Privacy model →](docs/privacy.md)**
+
+## Configuration
+
+Everything is optional with sensible defaults — port, DB path, scan roots, GitHub token, and
+more are environment variables documented in [Getting started](docs/getting-started.md#configuration)
+and [`.env.example`](.env.example).
+
+## Documentation
+
+| Page | What's in it |
 |---|---|
-| `docs/adr/ADR-100-stack.md` | Accepted MVP stack: Node 22 LTS + TypeScript + better-sqlite3, localhost UI (no Tauri/Electron for MVP) |
-| `docs/adr/ADR-100-shell-research-2026-08-21.md` | External research backing the localhost-UI decision |
-| `docs/planning/AgentWrangler_PRD_v0_7_0.md` | Product requirements v0.7.0 |
-| `docs/planning/AgentWrangler_Technical_Architecture_v4_5_0.md` | Architecture v4.5.0 |
-| `docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md` | SQLite schema + metric definitions v2 |
-| `docs/planning/AgentWrangler_Ingestion_and_Findings_Spec_v1.md` | Transcript ingestion + findings extractor spec |
-| `docs/planning/AgentWrangler_Recommendations_Engine_Spec_v1.md` | Recommendations engine spec |
-| `docs/planning/AgentWrangler_Spike_Plan_v2.md` | Spike exit criteria (authoritative) |
-| `docs/planning/AgentWrangler_PreImplementation_Plan_v1.md` | Session map + session prompts |
+| [Getting started](docs/getting-started.md) | Install paths, optional setup, configuration, troubleshooting |
+| [Dashboard tour](docs/dashboard-tour.md) | Every tab in depth, plus the metric vocabulary |
+| [Privacy model](docs/privacy.md) | Local storage, raw-checkpoint exception, and network integrations |
+| [Architecture](docs/planning/AgentWrangler_Technical_Architecture_v4_5_0.md) | Daemon, ingestion, detector, and query design |
+| [Data model & metrics](docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md) | SQLite schema and metric definitions |
+| [Contributing](.github/CONTRIBUTING.md) | Dev setup, checks, PR expectations |
+| [Security policy](.github/SECURITY.md) | Threat model and how to report a vulnerability |
+
+## Limitations
+
+- Reads Claude Code's JSONL transcript format; an upstream format change can require an
+  ingestion update.
+- Tested on Windows; macOS/Linux are believed working — reports welcome.
+- Single local user by design — no multi-user or team-aggregation mode.
+- Outcome linkage needs a read-only GitHub token; without one the feature stays inert (and
+  Settings says so — nothing fails silently).
+
+## License
+
+[Apache 2.0](LICENSE) © 2026 AgentWrangler contributors.
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md), [SECURITY.md](.github/SECURITY.md), and
+[CODE_OF_CONDUCT.md](.github/CODE_OF_CONDUCT.md).

package/dist/daemon/index.js

@@ -35,11 +35,11 @@ import { linkSessions } from "../outcomes/linker.js";
 import { syncAllWorkspaces } from "../outcomes/sync.js";
 import { generateWeeklyReport } from "../query/api/reports.js";
 import { setQueryDb } from "../query/db-context.js";
-import { setHealthInstance, setRuntimeResetHook } from "../query/settings-store.js";
+import { getSettingsData, setHealthInstance, setRuntimeResetHook, } from "../query/settings-store.js";
 import { loadConfig } from "./config.js";
 import { createServer } from "./http.js";
 import { createOutcomesPassRunner } from "./outcomes-pass.js";
-import { setReady } from "./readiness.js";
+import { setReady, setScanRoots, setScanState } from "./readiness.js";
 const VERSION = "0.1.0";
 /** Parse a named CLI argument: --name value or --name=value. */
 function getArg(name) {
@@ -110,6 +110,8 @@ if (isSmoke) {
         "apply_jobs",
         "analysis_runs",
         "ingest_quarantine",
+        "ingest_metric_events",
+        "ingest_metric_baselines",
         "ingest_offsets",
         "schema_migrations",
         "user_config",
@@ -208,7 +210,9 @@ function kickBootScan() {
 }
 async function runBootScan() {
     try {
-        const ingestor = new Ingestor(db, config.scanRoots, {
+        const scanRoots = getSettingsData(db).scan_roots;
+        setScanRoots(scanRoots);
+        const ingestor = new Ingestor(db, scanRoots, {
             onNewMappings: (count) => {
                 console.log(`Discovery mapped ${count} new repo(s) — scheduling outcomes pass`);
                 runOutcomesPass().catch((e) => {
@@ -218,10 +222,12 @@ async function runBootScan() {
         });
         setHealthInstance(ingestor.health);
         handle = await ingestor.startTailBatched();
+        setScanState("complete");
         setRuntimeResetHook(() => ingestor.clearRuntimeState());
         console.log(`Ingestion: initial scan complete — health ${JSON.stringify(ingestor.healthSnapshot())}`);
     }
     catch (e) {
+        setScanState("failed");
         console.error(`Ingestion failed to start — serving dashboard in degraded mode: ${e instanceof Error ? e.message : String(e)}`);
     }
     // After the initial back-scan, workspaces are discovered — re-probe so per-workspace

package/dist/daemon/readiness.js

@@ -4,7 +4,32 @@
  * Set to true by index.ts after the initial back-scan completes.
  * Read by http.ts to decide whether to serve the loading page or the real SPA.
  */
-const state = { ready: false };
+import * as fs from "node:fs";
+const state = { ready: false, scan: "scanning", scanRoots: [] };
+/** Snapshot the roots actually used by the running ingestor, not pending settings. */
+export function setScanRoots(roots) {
+    state.scanRoots = [...roots];
+}
+export function setScanState(scan) {
+    state.scan = scan;
+}
+/** Aggregate-only diagnostics; never exposes a local path or filesystem error. */
+export function getScanStatus() {
+    let invalid = 0;
+    for (const root of state.scanRoots) {
+        try {
+            if (!fs.statSync(root).isDirectory()) {
+                invalid += 1;
+                continue;
+            }
+            fs.accessSync(root, fs.constants.R_OK);
+        }
+        catch {
+            invalid += 1;
+        }
+    }
+    return { scan_state: state.scan, invalid_scan_root_count: invalid };
+}
 /** Returns true after the initial back-scan + detector pass have finished. */
 export function isReady() {
     return state.ready;

package/dist/daemon/router.js

@@ -26,7 +26,7 @@ import { getSessionSpendPercentile, getWeeklySelfPercentile, } from "../query/ap
 import { getFlavorDecomposition } from "../query/api/spend-flavor.js";
 import { getCacheWriteTrend, getTrends } from "../query/api/trends.js";
 import { getSettingsData } from "../query/settings-store.js";
-import { isReady } from "./readiness.js";
+import { getScanStatus, isReady } from "./readiness.js";
 function sendJson(res, status, body) {
     const payload = JSON.stringify(body);
     res.writeHead(status, {
@@ -741,6 +741,8 @@ export function handleApiRequest(_db, req, res, method, url) {
                 sessions,
                 files_seen: parser_health.files_seen,
                 files_parsed: parser_health.files_parsed,
+                lines_quarantined: parser_health.lines_quarantined,
+                ...getScanStatus(),
             });
             return;
         }

package/dist/db/migrations/016_ingest_offset_file_version.sql

@@ -0,0 +1,8 @@
+-- Nullable metadata lets existing offsets establish a baseline on their next read.
+-- No transcript content is stored here. Identity detects path replacement; timestamps
+-- detect equal-size in-place rewrites beyond the existing 256-byte head fingerprint.
+ALTER TABLE ingest_offsets ADD COLUMN file_size INTEGER;
+ALTER TABLE ingest_offsets ADD COLUMN file_dev TEXT;
+ALTER TABLE ingest_offsets ADD COLUMN file_ino TEXT;
+ALTER TABLE ingest_offsets ADD COLUMN file_mtime_ms REAL;
+ALTER TABLE ingest_offsets ADD COLUMN file_ctime_ms REAL;

package/dist/db/migrations/017_ingest_metric_events.sql

@@ -0,0 +1,22 @@
+-- Persist structural metric events so transcript replay cannot inflate session counters.
+-- event_id is a SHA-256 digest computed in-process; transcript content is never stored.
+CREATE TABLE ingest_metric_events (
+  event_id          TEXT PRIMARY KEY,
+  session_id        TEXT NOT NULL,
+  user_turn_ts      TEXT,
+  is_user_turn      INTEGER NOT NULL CHECK (is_user_turn IN (0, 1)),
+  is_compact_summary INTEGER NOT NULL CHECK (is_compact_summary IN (0, 1)),
+  is_api_error      INTEGER NOT NULL CHECK (is_api_error IN (0, 1)),
+  is_interrupt      INTEGER NOT NULL CHECK (is_interrupt IN (0, 1))
+);
+
+CREATE INDEX idx_ingest_metric_events_session_user_ts
+  ON ingest_metric_events(session_id, user_turn_ts)
+  WHERE is_user_turn = 1;
+
+-- Existing offsets predate the event ledger. Their consumed prefixes are seeded into
+-- the ledger without incrementing counters, then this durable boundary is advanced.
+CREATE TABLE ingest_metric_baselines (
+  file_path     TEXT PRIMARY KEY,
+  seeded_offset INTEGER NOT NULL CHECK (seeded_offset >= 0)
+);

package/dist/detector/measurement.js

@@ -20,6 +20,7 @@
  *
  * Injected `now: Date` everywhere — never call new Date() in this module.
  */
+import { PREMIUM_MODEL_SQL } from "../ingest/pricing.js";
 import { GLOBAL_WORKSPACE_ID } from "./context-probe.js";
 import { isD1SourceBackedRecommendation, parseD1SourceIdentity } from "./d1-source-identity.js";
 /** Wait ≥1 day after adoption before entering MEASURING. */
@@ -82,14 +83,14 @@ function avgFloorContext(db, scopeWorkspaceId, fromIso, toIso) {
 /**
  * D4 signal: routing-adherence score = ROUND(100 × (1 − premium_share)) over
  * non-sidechain reconciled turns in [fromIso, toIso), where premium = model
- * contains 'opus'. The data-model's "mechanical turn" classifier is not yet
+ * matches PREMIUM_MODEL_SQL (Opus/Fable/Mythos). The data-model's "mechanical turn" classifier is not yet
  * shipped, so all reconciled turns are the mechanical set (conservative proxy —
  * documented in the W4 build digest).
  */
 function routingAdherenceScore(db, scopeWorkspaceId, fromIso, toIso) {
     const scoped = scopeWorkspaceId !== null;
     const sql = `SELECT COUNT(*) AS n,
-                      AVG(CASE WHEN model LIKE '%opus%' THEN 1.0 ELSE 0.0 END) AS premium_share
+                      AVG(CASE WHEN ${PREMIUM_MODEL_SQL} THEN 1.0 ELSE 0.0 END) AS premium_share
                  FROM turns
                 WHERE is_sidechain = 0 AND provisional = 0 AND ts >= ? AND ts < ? ${scoped ? "AND workspace_id = ?" : ""}`;
     const params = scoped ? [fromIso, toIso, scopeWorkspaceId] : [fromIso, toIso];

package/dist/hook/precompact-checkpoint-hook.mjs

@@ -53,6 +53,32 @@ export function writeCheckpoint(transcriptPath, sessionId, dir, now = new Date()
   return dest;
 }
 
+/**
+ * Return the timestamp encoded by a snapshot filename, or null for files this hook did
+ * not create. Malformed .jsonl files are deliberately left alone by retention.
+ */
+function snapshotTimestamp(name) {
+  const match = /-(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z-\d{6}\.jsonl$/.exec(
+    name,
+  );
+  if (!match) return null;
+  const [, year, month, day, hour, minute, second, millisecond] = match;
+  const timestamp = Date.parse(
+    `${year}-${month}-${day}T${hour}:${minute}:${second}.${millisecond}Z`,
+  );
+  if (Number.isNaN(timestamp)) return null;
+  const parsed = new Date(timestamp);
+  return parsed.getUTCFullYear() === Number(year) &&
+    parsed.getUTCMonth() + 1 === Number(month) &&
+    parsed.getUTCDate() === Number(day) &&
+    parsed.getUTCHours() === Number(hour) &&
+    parsed.getUTCMinutes() === Number(minute) &&
+    parsed.getUTCSeconds() === Number(second) &&
+    parsed.getUTCMilliseconds() === Number(millisecond)
+    ? timestamp
+    : null;
+}
+
 /** Prune oldest snapshots beyond the count cap, then beyond the total-byte cap. */
 export function enforceRetention(dir, maxCount = MAX_COUNT, maxBytes = MAX_BYTES) {
   let entries;
@@ -60,30 +86,40 @@ export function enforceRetention(dir, maxCount = MAX_COUNT, maxBytes = MAX_BYTES
     entries = fs
       .readdirSync(dir)
       .filter((name) => name.endsWith(".jsonl"))
-      .sort() // timestamp-derived names sort chronologically
       .map((name) => {
         const full = path.join(dir, name);
-        return { full, size: fs.statSync(full).size };
-      });
+        const timestamp = snapshotTimestamp(name);
+        if (timestamp === null) return null;
+        try {
+          const stat = fs.statSync(full);
+          if (!stat.isFile()) return null;
+          return { full, name, size: stat.size, timestamp, mtimeMs: stat.mtimeMs };
+        } catch {
+          // A vanished or unreadable entry must not prevent pruning known snapshots.
+          return null;
+        }
+      })
+      .filter((entry) => entry !== null)
+      .sort(
+        (a, b) =>
+          a.timestamp - b.timestamp || a.mtimeMs - b.mtimeMs || a.name.localeCompare(b.name),
+      );
   } catch {
     return; // dir missing or unreadable — nothing to prune
   }
 
-  const removeOldest = () => {
-    const victim = entries.shift();
-    if (!victim) return;
+  let count = entries.length;
+  let total = entries.reduce((sum, entry) => sum + entry.size, 0);
+  for (const victim of entries) {
+    if (count <= maxCount && total <= maxBytes) break;
     try {
       fs.rmSync(victim.full);
-    } catch {
-      // A locked or already-removed snapshot is not worth failing for.
+    } catch (error) {
+      // A locked snapshot still counts. Try each later candidate at most once.
+      if (error?.code !== "ENOENT") continue;
     }
-  };
-
-  while (entries.length > maxCount) removeOldest();
-  let total = entries.reduce((sum, entry) => sum + entry.size, 0);
-  while (entries.length > 0 && total > maxBytes) {
-    total -= entries[0].size;
-    removeOldest();
+    count -= 1;
+    total -= victim.size;
   }
 }