# Offline stats and portable snapshots Build the committed `dist/pi-stats-export.mjs` with `npm ci && npm run build:stats-export`. The exact esbuild version and dependencies are locked; tests assert byte-identical rebuilds. Copy only that file. Runtime is Node 22+ with builtins only, no Pi install, extension, private repository, package install, auth or network access. ``` node ARTIFACT export --agent-dir DIR --output OUT [--sessions-dir ROOT] node ARTIFACT import --agent-dir DIR --input REPO ``` `--agent-dir` defaults to `PI_CODING_AGENT_DIR`, then `~/.pi/agent`. The session root defaults to `PI_CODING_AGENT_SESSION_DIR`, then `DIR/sessions`; `--sessions-dir` takes precedence. History already cached under former roots is retained, even after files disappear. Paths are resolved locally and never exported. Run export before fetch/commit/push, then import the updated data checkout. Git, locking concurrent sync runs, retrying pushes and network deadlines belong to the sync helper, not this data-only artifact. CLI results: - Export: `{ "machineId": "", "snapshotDir": "/machines/" }` on stdout. - Import: `{ "imported": N, "retained": N, "problems": [], "importedAt": MS }` on stdout. - Exactly one JSON object is emitted. Diagnostics go to stderr. Invalid commands, malformed local scans, unwritable caches and publication failures exit nonzero. Partial/corrupt imports emit a JSON result and exit nonzero, retaining every failed machine's last-good snapshot. - A failed export never replaces the previous manifest. Its validated immutable shards may remain unpublished. Export writes only its own machine directory; it never edits another machine. Installation state, never synced: - `DIR/pi-session-kit/machine.json`: persistent UUID v4 and label, created exclusively and atomically on first use. Default label is `Pi machine`, not the hostname. A corrupt identity fails rather than silently enrolling another machine. Copying an entire agent dir also copies its installation identity: remove `machine.json` on a genuinely new installation before export. - `DIR/pi-session-kit/stats-cache.json`: local parser cache v2, including file paths and compact usage tuples. Version 1 entries for deleted files stay intact; existing files reparse even if their mtime/size match. Strong identities are not invented for inaccessible legacy files. - `DIR/pi-session-kit/stats-global.json`: one atomically replaced document containing validated last-good machine snapshots, last successful import time and coverage problems. Imports do not mutate local usage or installation identity. A wholly failed import does not advance the sync time; a partial import records valid updates and marks coverage incomplete. Snapshot version 1: ``` machines//manifest.json machines//-.json ``` Manifest exact keys: - `version`: `1`. - `machineId`: persistent UUID v4, matching its directory. - `label`: installation label, maximum 1024 characters. Not a session name. - `exportedAt`: positive UTC Unix milliseconds. - `shards`: unique month references, each exactly `{month, file, sha256, bytes}`. `file` MUST equal `-.json`. No absolute paths, traversal or arbitrary filenames. Shard exact keys: `{version, machineId, month, events, sessions}`. All shard JSON is canonical `JSON.stringify` output (no indentation/newline), bounded to 128 MiB per file. Manifest hashes cover exact UTF-8 shard bytes. Immutable content-addressed shards are published first, manifest last; unreferenced old shard generations are deliberately retained and ignored. No cleanup races with readers. Each manifest references exactly one shard per month. Event exact keys: - `id`: SHA-256 event fingerprint. - `entryId`: SHA-256 of `entry:`, or `null` for legacy records. - `sessionId`: opaque session ID. - `ms`: original positive UTC Unix milliseconds, in the shard's UTC month. - `provider`, `model`: raw physical attribution, each nonempty and at most 1024 characters. - `input`, `output`, `cacheRead`, `cacheWrite`: nonnegative safe integers, not all zero. - `cost`: finite nonnegative recorded notional cost. The identified fingerprint is SHA-256 of the JSON array `[entryId, ms, provider, model, input, output, cacheRead, cacheWrite]`. Notional price changes do not create new events. Different entry IDs survive equal usage. Copied entries across forks/machines count once. Legacy fingerprinting and matching use `[provider, model, ms, input, output, cacheRead, cacheWrite]`, intentionally without cost to preserve the old tuple rule; identified counterparts supersede legacy duplicates. Session exact keys: `{id, startMs, endMs, child}`. Header IDs hash as `session:
`; unidentified legacy sessions use a local path hash and therefore cannot always be matched across machines. Session metadata is independent of event dedup, lives in the start timestamp's UTC month, and merges time bounds by ID through the same helper for local and imported histories. Children retain usage but do not contribute to session count. Only sessions owning a retained event count. The oldest session owns copied events, independent of machine read order. Every exported event references session metadata. No message content, tool arguments/results, paths, session names, environment, credentials or source objects are exported. Explicit projections, not object spreads, enforce the allowlist. Raw attribution is retained to avoid display-sanitization collisions. Schema validators reject unknown fields, unsupported versions, duplicate IDs, invalid counters/time/months, excluded test providers, identity/digest/byte-size mismatches, symlink files and missing session metadata. Import validates a whole machine before replacement, retaining last-good data for bad, missing or older snapshots. Other valid machines still advance. Only the final validated global document is atomically renamed, so `/stats` sees either the old or new complete cache, never a mixed import. Producer updates are invisible until the producer exports AND the viewer imports. Coverage counts known machines, not undiscovered installations; it is not proof that every machine has synced. `/stats` freshly scans local sessions and combines them with this cache without network access. Its UI labels cached coverage, successful import time, local-only/never-synced state and incomplete coverage. Future calls are ignored in display totals, not removed from durable history. Statistics are not subscription quota measurements or router inputs. Harness API: - `src/stats/library.ts` is a Pi-independent barrel for parser, aggregation and snapshot APIs. - `parseSession`, `flatten`, `dedupCalls`, `hourlySeries`, `makeSnapshot`, `validateManifest`, `validateShard`, `validateSnapshot`, `exportStats`, `importStats`, `loadCombined`, `coverageLabel`. - `hourlySeries(calls, "5h" | "24h", now, keyOf?)` is deterministic, zero-filled, filters exact rolling boundaries and labels partial edges. UTC buckets keep repeated DST hours separate; viewer-local labels carry UTC offsets, including fractional-offset zones. Limits: legacy no-ID copies can only use tuple dedup, legacy session metadata without header IDs cannot reliably match across machines, and concurrent sync workflows must serialize writes to one agent directory. The combined global cache is bounded to 128 MiB; a larger import fails without replacing last-good data. There is no automatic discovery/network refresh or daemon. Reinitializing both the local parser cache and source history permanently loses that machine's local history; keep these installation files out of synced snapshots but do not routinely delete them.