@faithfulalabi/agent-lens 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faithful Alabi
+
+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.

package/README.md

@@ -0,0 +1,124 @@
+# agent-lens
+
+A local-first tracing platform for coding agents. Run one command, open a local UI, and read back
+everything a Claude Code session did — prompts, tool calls, sub-agents, inputs and outputs — so you
+can see where a session went and steer the next one better.
+
+It reads the transcripts Claude Code already writes to disk. There is nothing to add to your
+harness and nothing to configure.
+
+## Quickstart
+
+```bash
+npx @faithfulalabi/agent-lens
+```
+
+That starts the local server and the UI and prints the URL. Open it. Sessions you have already run
+are there; new ones show up as they happen.
+
+Requires Node.js `>=24`.
+
+## The durability contract — read this before you delete anything
+
+Three directories, three completely different promises.
+
+| Path                     | What it is                                                                                                            | What deleting it costs                                                                      |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `~/.claude/projects`     | The **source**. Claude Code owns it, writes it, and expires files from it on its own schedule. agent-lens only reads. | Not your call — Claude Code is already doing it. That is the whole reason this tool exists. |
+| `~/.agent-lens/archive`  | The **system of record**. A verbatim mirror: the same bytes at a different path, append-only, never written back.     | **Everything past the source's cliff.** There is no other copy.                             |
+| `~/.agent-lens/cache.db` | A **disposable** cache — search indexes and projections, all derived.                                                 | Nothing. It rebuilds from the archive.                                                      |
+
+> **rm cache.db loses nothing. rm -rf ~/.agent-lens/archive loses data permanently.**
+
+The inversion is the point. The directory that looks canonical is the one being erased, and the
+unremarkable one in your home directory is the one holding the only surviving copy.
+
+### The limitation, stated plainly
+
+> **agent-lens can only archive what exists while it runs — a gap in uptime is a gap in the record.**
+
+A coverage figure of 100% is 100% _of the survivors_. Anything Claude Code expired before the
+archive existed, or during a long gap in it, is gone and no tool can bring it back.
+
+What the archive does hold, it holds forever. The shape is consistent even though the numbers are
+not: the source thins out with age and then stops — past a cliff a few weeks back there is nothing
+left in it at all — while the archive keeps going. Every session older than that cliff exists only
+in the archive.
+
+Do not take a number from this page. Your corpus is not the author's, and both move day to day.
+`agent-lens doctor` prints yours, including how many files have no live source left and are held
+only by the archive.
+
+## Keeping the archive current
+
+```bash
+agent-lens schedule install
+```
+
+On macOS that sets up a launchd job that runs `agent-lens archive` every 15 minutes and logs each
+pass where `agent-lens doctor` reads it. Run it again any time — it replaces its own job rather
+than duplicating it. `agent-lens schedule status` reports the job and its last successful pass;
+`agent-lens schedule disable` turns it off cleanly, leaving the archive and its logs untouched. On
+other platforms, run `agent-lens archive` every ~15 minutes yourself via a systemd timer or cron.
+
+One caveat worth knowing before you rely on an interval: a wall-clock schedule does not fire while
+the machine is asleep. Treat the interval as a bound on _wake_ time, not on elapsed time.
+
+The pass is safe to run often: an advisory lock means a second concurrent pass copies nothing and
+exits 0, and an unchanged corpus copies zero bytes. When a source has been rewritten, the archived
+bytes are **kept** and the file is marked `diverged` rather than overwritten. `agent-lens archive
+--verify` is the full-file integrity audit — **not for the scheduled pass**; run it by hand or on a
+weekly schedule.
+
+## `agent-lens doctor` — what is protected, and what is not
+
+`doctor` reads both trees and reports archive coverage, integrity, total archive bytes split hot vs
+sealed, every diverged file, and Claude Code's own retention setting. It **writes nothing** — not
+the archive, not the log, not the lock, and never anything belonging to your harness. It reports
+retention; it does not repair it.
+
+```bash
+agent-lens doctor --verify
+```
+
+| Flag                     | Meaning                                                                                       |
+| ------------------------ | --------------------------------------------------------------------------------------------- |
+| `--json`                 | emit the full report as one JSON line                                                         |
+| `--dataDir <dir>`        | override `~/.agent-lens`                                                                      |
+| `--transcriptRoot <dir>` | override `~/.claude/projects`                                                                 |
+| `--settingsPath <file>`  | override where the harness retention setting is read from (also `AGENT_LENS_CLAUDE_SETTINGS`) |
+| `--verify`               | recompute the full prefix hash — the real audit, not the sampled one                          |
+
+Read the integrity line carefully. It prints three counts that sum to the number of archived files:
+**verified**, **diverged** and **unverifiable**. A file is unverifiable when nothing exists to check
+it against — its source has already expired, or it is sealed — and there is no stored per-file hash
+yet. Those files are never counted as verified. On a machine that has been off for a month, expect
+unverifiable to be the large one. That is the truthful answer, not a failure.
+
+`doctor` also reports the time since the archive job's last successful pass, read from the job's
+own log (`~/.agent-lens/logs/cron.log`) and never from a file mtime — a job that has not run is a
+different, more urgent fact than one that ran and found nothing new to copy.
+
+## Starting the server
+
+```bash
+agent-lens start
+```
+
+| Flag            | Meaning                                                                                                       |
+| --------------- | ------------------------------------------------------------------------------------------------------------- |
+| `--port <n>`    | bind port (auto-increments on collision)                                                                      |
+| `--host <host>` | bind host. Defaults to loopback; anything else prints a network-exposure warning and is your decision to make |
+
+The server binds `127.0.0.1` by default and every `/api/*` request carries a token. See
+[SECURITY.md](SECURITY.md) for the trust boundary, including the one property that surprises
+people: on a shared machine, the agent being traced can read the trace API too.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the render loop against a real corpus, and the
+one-door rule every change to transcript reading has to satisfy.
+
+## License
+
+MIT.

package/bin/agent-lens.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// The published entry point. It runs the BUILT CLI in-process: no transpiler, no
+// source tree, no child process.
+//
+// In-process is load-bearing, not a tidy-up. The previous shim launched a child
+// with a transpiler forking underneath it: a three-process chain that swallowed
+// signals, recorded at src/cli/__tests__/start-signals.test.ts:7-12. Calling
+// `main` here puts SIGINT/SIGTERM/SIGHUP straight onto the handlers
+// `commands/start` registers, so `agent-lens start` survives a real kill.
+//
+// The tokens this file must never contain are therefore spelled nowhere in it,
+// prose included — the render gate's own precedent for a substring pin, since a
+// comment satisfies `toContain` just as well as code does. The list lives in
+// src/packaging.test.ts, under "resolves the built CLI in-process".
+//
+// The UI still resolves: `resolveUiDir` in src/server/static-ui walks up to the
+// nearest package.json instead of using a fixed relative path, precisely because
+// the built server sits one directory deeper than the source one.
+
+const MIN_NODE_MAJOR = 24;
+const major = Number.parseInt(process.versions.node, 10);
+
+if (!Number.isInteger(major) || major < MIN_NODE_MAJOR) {
+  // Ahead of the import, never after it. The CLI graph reaches node:sqlite
+  // (src/db/open) and zstd (src/archive/seal), so on an older Node the first
+  // symptom would be ERR_UNKNOWN_BUILTIN_MODULE from deep inside the DB layer.
+  // npm will not catch it either: `engine-strict` defaults to false, which makes
+  // the `engines` field a warning that installs anyway.
+  process.stderr.write(
+    `agent-lens needs Node 24 or newer; this is Node ${process.versions.node}.\n`,
+  );
+  process.exitCode = 1;
+} else {
+  // Dynamic, so the guard above runs first — a static import would hoist past it.
+  const { main } = await import('../dist/src/cli/index.js');
+  // Setting the code and returning, rather than terminating the process here:
+  // the abrupt form truncates piped stdout mid-write. Exit codes 0/1/3 from
+  // `commands/archive` flow through unchanged either way.
+  process.exitCode = await main(process.argv.slice(2));
+}

package/bin/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "main": "agent-lens.js"
+}

package/dist/src/archive/cron-log.js

@@ -0,0 +1,41 @@
+import { readFileSync } from 'node:fs';
+import { lstatSafe, resolveCronLogPath } from './paths.js';
+const ENTRY = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})([+-])(\d{2})(\d{2})\s+(\S+)\s*(.*)$/;
+export function parseCronLog(text) {
+    const entries = [];
+    for (const line of text.split('\n')) {
+        const match = ENTRY.exec(line);
+        if (match === null)
+            continue;
+        const [, y, mo, d, h, mi, s, sign, offH, offM, status, summary] = match;
+        const offsetMs = (sign === '-' ? -1 : 1) * (Number(offH) * 60 + Number(offM)) * 60_000;
+        entries.push({
+            epochMs: Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s)) - offsetMs,
+            status: status,
+            summary: summary?.trim() ?? '',
+        });
+    }
+    return entries;
+}
+export function readCronLogStatus(dataDir) {
+    const path = resolveCronLogPath(dataDir);
+    if (lstatSafe(path)?.isFile() !== true)
+        return { state: 'absent', path };
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return { state: 'empty', path };
+    }
+    const entries = parseCronLog(text);
+    const lastEntry = entries.at(-1);
+    if (lastEntry === undefined)
+        return { state: 'empty', path };
+    return {
+        state: 'found',
+        path,
+        lastEntry,
+        lastOk: entries.findLast((entry) => entry.status === 'ok'),
+    };
+}

package/dist/src/archive/discover.js

@@ -0,0 +1,89 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { relativeUnder } from './paths.js';
+const SESSION_SUBDIRS = ['subagents', 'tool-results'];
+const ALLOWED_SUFFIXES = ['.jsonl', '.meta.json', '.txt'];
+const SEALED_SUFFIX = '.zst';
+function readDirSafe(dir, wantDirs) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => (wantDirs ? entry.isDirectory() : entry.isFile()))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+function isAllowed(name) {
+    return ALLOWED_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+function walkRecursive(dir, stripSealed, out) {
+    for (const name of readDirSafe(dir, false)) {
+        if (isAllowed(stripSealed ? stripSealedSuffix(name).name : name)) {
+            out.push(join(dir, name));
+        }
+    }
+    for (const child of readDirSafe(dir, true)) {
+        walkRecursive(join(dir, child), stripSealed, out);
+    }
+}
+function stripSealedSuffix(name) {
+    return name.endsWith(SEALED_SUFFIX)
+        ? { name: name.slice(0, -SEALED_SUFFIX.length), sealed: true }
+        : { name, sealed: false };
+}
+function walkRoot(root, stripSealed) {
+    const found = [];
+    for (const slug of readDirSafe(root, true)) {
+        const slugDir = join(root, slug);
+        for (const name of readDirSafe(slugDir, false)) {
+            const stem = stripSealed ? stripSealedSuffix(name).name : name;
+            if (stem.endsWith('.jsonl'))
+                found.push(join(slugDir, name));
+        }
+        for (const session of readDirSafe(slugDir, true)) {
+            for (const sub of SESSION_SUBDIRS) {
+                walkRecursive(join(slugDir, session, sub), stripSealed, found);
+            }
+        }
+    }
+    return found;
+}
+export function discover(sourceRoot, archiveRoot) {
+    const entries = new Map();
+    for (const sourcePath of walkRoot(sourceRoot, false)) {
+        const relPath = relativeUnder(sourceRoot, sourcePath);
+        if (relPath === undefined)
+            continue;
+        entries.set(relPath, {
+            relPath,
+            sourcePath,
+            archivePath: join(archiveRoot, relPath),
+            presence: 'source-only',
+            sealed: false,
+        });
+    }
+    for (const found of walkRoot(archiveRoot, true)) {
+        const { sealed } = stripSealedSuffix(found);
+        const archivePath = sealed ? found.slice(0, -SEALED_SUFFIX.length) : found;
+        const relPath = relativeUnder(archiveRoot, archivePath);
+        if (relPath === undefined)
+            continue;
+        const sourcePath = join(sourceRoot, relPath);
+        const existing = entries.get(relPath);
+        if (existing === undefined) {
+            entries.set(relPath, {
+                relPath,
+                sourcePath,
+                archivePath,
+                presence: 'archive-only',
+                sealed,
+            });
+        }
+        else {
+            existing.presence = 'both';
+            existing.sealed ||= sealed;
+        }
+    }
+    return [...entries.values()].sort((a, b) => (a.relPath < b.relPath ? -1 : 1));
+}

package/dist/src/archive/index.js

@@ -0,0 +1,7 @@
+export { archiveOnce, createMirrorContext, mirrorFile } from './mirror.js';
+export { discover } from './discover.js';
+export { buildDoctorReport, SEALED_LEGACY_REASON } from './report.js';
+export { acquireLock } from './lock.js';
+export { parseCronLog, readCronLogStatus } from './cron-log.js';
+export { resolveArchiveLogPath, resolveArchiveRoot, resolveCronLogPath, resolveDataDir, resolveLockPath, resolveTranscriptRoot, } from './paths.js';
+export { assertNotUnderRoot, assertUnderRoot, DATA_DIR_LABEL, TRANSCRIPT_ROOT_LABEL, } from './paths.js';

package/dist/src/archive/lock.js

@@ -0,0 +1,119 @@
+import { closeSync, openSync, readFileSync, unlinkSync, writeSync } from 'node:fs';
+import { hostname as osHostname } from 'node:os';
+import { dirname } from 'node:path';
+import { assertUnderRoot, DATA_DIR_LABEL, ensureDirUnder, resolveLockPath, statSafe, } from './paths.js';
+export const MAX_LOCK_AGE_MS = 60 * 60 * 1000;
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return 'alive';
+    }
+    catch (error) {
+        return error.code === 'EPERM' ? 'permission-denied' : 'dead';
+    }
+}
+function parseRecord(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return undefined;
+        const { pid, started_at, hostname } = parsed;
+        if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0)
+            return undefined;
+        return {
+            pid,
+            started_at: typeof started_at === 'number' ? started_at : 0,
+            hostname: typeof hostname === 'string' ? hostname : '',
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function tryCreate(lockPath, record) {
+    let fd;
+    try {
+        fd = openSync(lockPath, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    try {
+        writeSync(fd, JSON.stringify(record));
+    }
+    finally {
+        closeSync(fd);
+    }
+    return true;
+}
+export function releaseLock(lockPath, pid) {
+    try {
+        const record = parseRecord(readFileSync(lockPath, 'utf8'));
+        if (record?.pid === pid)
+            unlinkSync(lockPath);
+    }
+    catch {
+    }
+}
+export function acquireLock(dataDir, identity = {}, lockPath = resolveLockPath(dataDir)) {
+    const pid = identity.pid ?? process.pid;
+    const hostname = identity.hostname ?? osHostname();
+    const now = identity.now ?? Date.now();
+    const isAlive = identity.isAlive ?? defaultIsAlive;
+    ensureDirUnder(dirname(lockPath), dataDir, DATA_DIR_LABEL);
+    assertUnderRoot(lockPath, dataDir, DATA_DIR_LABEL);
+    const mine = { pid, started_at: now, hostname };
+    if (tryCreate(lockPath, mine)) {
+        return {
+            state: { state: 'acquired', holder_pid: pid },
+            release: () => releaseLock(lockPath, pid),
+        };
+    }
+    let raw;
+    try {
+        raw = readFileSync(lockPath, 'utf8');
+    }
+    catch {
+        return tryCreate(lockPath, mine)
+            ? { state: { state: 'acquired', holder_pid: pid }, release: () => releaseLock(lockPath, pid) }
+            : { state: { state: 'held' }, release: () => { } };
+    }
+    const record = parseRecord(raw);
+    const held = (extra) => ({
+        state: { state: 'held', ...extra },
+        release: () => { },
+    });
+    if (record === undefined) {
+        const mtime = statSafe(lockPath)?.mtimeMs ?? 0;
+        const age = now - mtime;
+        if (age <= MAX_LOCK_AGE_MS)
+            return held({ age_ms: age });
+        return reclaim(lockPath, mine, 'unparseable', undefined, age);
+    }
+    const age = now - record.started_at;
+    const liveness = isAlive(record.pid);
+    if (liveness === 'permission-denied')
+        return held({ holder_pid: record.pid, age_ms: age });
+    if (liveness === 'alive' && record.hostname === hostname) {
+        return held({ holder_pid: record.pid, age_ms: age });
+    }
+    if (liveness === 'dead')
+        return reclaim(lockPath, mine, 'esrch', record.pid, age);
+    return reclaim(lockPath, mine, 'foreign-host', record.pid, age);
+}
+function reclaim(lockPath, mine, reason, holderPid, ageMs) {
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+    }
+    if (!tryCreate(lockPath, mine)) {
+        return { state: { state: 'held', holder_pid: holderPid, age_ms: ageMs }, release: () => { } };
+    }
+    return {
+        state: { state: 'reclaimed', holder_pid: holderPid, age_ms: ageMs, reclaim_reason: reason },
+        release: () => releaseLock(lockPath, mine.pid),
+    };
+}

package/dist/src/archive/log.js

@@ -0,0 +1,15 @@
+import { appendOwnedLine, resolveArchiveLogPath } from './paths.js';
+export function isQuiet(record) {
+    return (record.bytes_copied === 0 &&
+        record.diverged.length === 0 &&
+        record.newly_expired.length === 0 &&
+        record.errors.length === 0 &&
+        record.lock.state === 'acquired' &&
+        record.sealed.length === 0);
+}
+export function appendArchiveLog(dataDir, record) {
+    if (isQuiet(record))
+        return false;
+    appendOwnedLine(resolveArchiveLogPath(dataDir), `${JSON.stringify(record)}\n`, dataDir);
+    return true;
+}