@swestash/agent-lens 0.8.0 → 0.8.2

package/dist/agent-lens.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { existsSync as existsSync9, readFileSync as readFileSync8, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname6, join as join12 } from "path";
+import { dirname as dirname6, join as join13 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // ../../node_modules/.pnpm/cac@6.7.14/node_modules/cac/dist/index.mjs
@@ -1339,14 +1339,72 @@ function resolveWebDist(fromDir, repoRoot = findRepoRoot(fromDir)) {
   return installed;
 }
 
-// ../core/dist/sources.js
+// ../core/dist/config.js
 import { readFileSync as readFileSync2 } from "fs";
-function readConfig() {
+import { join as join2 } from "path";
+var DEFAULT_PORT = 4477;
+var DEFAULT_HOST = "127.0.0.1";
+var DEFAULT_DB_NAME = "agent-lens.db";
+function readConfigFile() {
   const repoRoot = findRepoRoot();
   const dataDir = resolveDataDir(repoRoot);
   const file = resolveConfigFile(repoRoot, dataDir);
   return file ? JSON.parse(readFileSync2(file, "utf8")) : null;
 }
+function resolveDbPath(override, cfg = readConfigFile()) {
+  if (override)
+    return { path: override, origin: "flag" };
+  if (process.env.AGENT_LENS_DB)
+    return { path: process.env.AGENT_LENS_DB, origin: "env" };
+  if (isSet(cfg?.db))
+    return { path: expandPath(String(cfg.db).trim()), origin: "file" };
+  return { path: join2(resolveDataDir(findRepoRoot()), DEFAULT_DB_NAME), origin: "default" };
+}
+function validatePort(value, source) {
+  const n = typeof value === "number" ? value : Number(String(value).trim());
+  if (!Number.isInteger(n) || n < 1 || n > 65535) {
+    throw new Error(`agent-lens: invalid port from ${source}: '${value}' (expected an integer 1-65535)`);
+  }
+  return n;
+}
+function isSet(v) {
+  return v !== void 0 && v !== null && String(v).trim() !== "";
+}
+function resolveServerConfig(overrides = {}, cfg = readConfigFile()) {
+  let port;
+  let portOrigin;
+  if (isSet(overrides.port)) {
+    port = validatePort(overrides.port, "--port");
+    portOrigin = "flag";
+  } else if (isSet(process.env.AGENT_LENS_PORT)) {
+    port = validatePort(process.env.AGENT_LENS_PORT, "AGENT_LENS_PORT");
+    portOrigin = "env";
+  } else if (isSet(cfg?.server?.port)) {
+    port = validatePort(cfg.server.port, "server.port (config file)");
+    portOrigin = "file";
+  } else {
+    port = DEFAULT_PORT;
+    portOrigin = "default";
+  }
+  let host;
+  let hostOrigin;
+  if (isSet(overrides.host)) {
+    host = String(overrides.host).trim();
+    hostOrigin = "flag";
+  } else if (isSet(process.env.AGENT_LENS_HOST)) {
+    host = process.env.AGENT_LENS_HOST.trim();
+    hostOrigin = "env";
+  } else if (isSet(cfg?.server?.host)) {
+    host = String(cfg.server.host).trim();
+    hostOrigin = "file";
+  } else {
+    host = DEFAULT_HOST;
+    hostOrigin = "default";
+  }
+  return { port, host, portOrigin, hostOrigin };
+}
+
+// ../core/dist/sources.js
 function loadSources() {
   if (process.env.CLAUDE_DIR) {
     return [
@@ -1357,7 +1415,7 @@ function loadSources() {
       }
     ];
   }
-  const cfg = readConfig() ?? { sources: [{ label: "default", agent: "claude-code", configDir: "$HOME/.claude" }] };
+  const cfg = readConfigFile() ?? { sources: [{ label: "default", agent: "claude-code", configDir: "$HOME/.claude" }] };
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const raw of cfg.sources || []) {
@@ -1377,7 +1435,7 @@ function loadExcludes() {
   const fromEnv = (process.env.AGENT_LENS_EXCLUDE || "").split(",");
   let fromCfg = [];
   if (!process.env.CLAUDE_DIR) {
-    const cfg = readConfig();
+    const cfg = readConfigFile();
     if (cfg && Array.isArray(cfg.exclude))
       fromCfg = cfg.exclude;
   }
@@ -1400,7 +1458,7 @@ function encodeProjectPath(p) {
 
 // ../core/dist/collect.js
 import { appendFileSync, closeSync, copyFileSync, existsSync as existsSync2, mkdirSync, openSync, readSync, readdirSync, statSync, unlinkSync, utimesSync, writeSync, chmodSync } from "fs";
-import { basename, dirname as dirname2, join as join2, relative, sep } from "path";
+import { basename, dirname as dirname2, join as join3, relative, sep } from "path";
 import { platform as platform2 } from "os";
 var POSIX = platform2() !== "win32";
 var DIR_MODE = 448;
@@ -1480,19 +1538,19 @@ function filesEqual(a, b) {
   return prefixEquals(a, b, sa.size);
 }
 function latestSnapshot(archive, relParts) {
-  const versRoot = join2(archive, ".versions");
+  const versRoot = join3(archive, ".versions");
   if (!existsSync2(versRoot))
     return null;
   const stamps = readdirSync(versRoot).sort();
   for (let i = stamps.length - 1; i >= 0; i--) {
-    const p = join2(versRoot, stamps[i], ...relParts);
+    const p = join3(versRoot, stamps[i], ...relParts);
     if (existsSync2(p))
       return p;
   }
   return null;
 }
 function snapshot(absPath, relParts, versionsDir, stats) {
-  const dst = join2(versionsDir, ...relParts);
+  const dst = join3(versionsDir, ...relParts);
   ensureDir(dirname2(dst));
   copyFileSync(absPath, dst);
   syncMeta(dst, statSync(absPath));
@@ -1500,7 +1558,7 @@ function snapshot(absPath, relParts, versionsDir, stats) {
 }
 function walkCollectable(dir, out, inWorkflows = false, inToolResults = false) {
   for (const e of readdirSync(dir, { withFileTypes: true })) {
-    const p = join2(dir, e.name);
+    const p = join3(dir, e.name);
     if (e.isDirectory()) {
       walkCollectable(p, out, inWorkflows || e.name === "workflows", inToolResults || e.name === "tool-results");
     } else if (e.isFile() && (e.name.endsWith(".jsonl") || inWorkflows || inToolResults || e.name.endsWith(".meta.json"))) {
@@ -1541,7 +1599,7 @@ function removeCredentials(dir) {
   if (!existsSync2(dir))
     return;
   for (const e of readdirSync(dir, { withFileTypes: true })) {
-    const p = join2(dir, e.name);
+    const p = join3(dir, e.name);
     if (e.isDirectory())
       removeCredentials(p);
     else if (e.name === ".credentials.json") {
@@ -1554,19 +1612,19 @@ function removeCredentials(dir) {
 }
 function collectSource(source, archiveBase, excludedDirs, runTs, stats, log) {
   const { label, configDir } = source;
-  const archive = join2(archiveBase, label);
-  const versionsDir = join2(archive, ".versions", runTs);
+  const archive = join3(archiveBase, label);
+  const versionsDir = join3(archive, ".versions", runTs);
   if (!existsSync2(configDir)) {
     log(`agent-lens: [${label}] source not found: ${configDir} (skipping)`);
     return;
   }
-  ensureDir(join2(archive, "projects"));
-  ensureDir(join2(archive, "settings"));
+  ensureDir(join3(archive, "projects"));
+  ensureDir(join3(archive, "settings"));
   const files = [];
-  const projectsDir = join2(configDir, "projects");
+  const projectsDir = join3(configDir, "projects");
   if (existsSync2(projectsDir))
     walkCollectable(projectsDir, files);
-  const historySrc = join2(configDir, "history.jsonl");
+  const historySrc = join3(configDir, "history.jsonl");
   if (existsSync2(historySrc))
     files.push(historySrc);
   const before = { scanned: stats.scanned, snapshots: stats.snapshots };
@@ -1579,13 +1637,13 @@ function collectSource(source, archiveBase, excludedDirs, runTs, stats, log) {
     if (excludedDirs.some((enc) => relPosix.startsWith(`projects/${enc}/`)))
       continue;
     stats.scanned++;
-    syncFile(src, join2(archive, ...relParts), relParts, archive, versionsDir, stats, base.endsWith(".jsonl"));
+    syncFile(src, join3(archive, ...relParts), relParts, archive, versionsDir, stats, base.endsWith(".jsonl"));
   }
   for (const f of ["settings.json", "settings.local.json"]) {
-    const s = join2(configDir, f);
+    const s = join3(configDir, f);
     if (!existsSync2(s))
       continue;
-    const a = join2(archive, "settings", f);
+    const a = join3(archive, "settings", f);
     if (existsSync2(a) && !filesEqual(s, a))
       snapshot(a, ["settings", f], versionsDir, stats);
     ensureDir(dirname2(a));
@@ -1598,13 +1656,13 @@ function collectSource(source, archiveBase, excludedDirs, runTs, stats, log) {
   const line = `${(/* @__PURE__ */ new Date()).toISOString()} run=${runTs} source=${label} scanned=${scanned} snapshots=${snapshots} archive=${archive}`;
   log(`agent-lens: ${line}`);
   try {
-    appendFileSync(join2(archiveBase, ".collect.log"), line + "\n");
+    appendFileSync(join3(archiveBase, ".collect.log"), line + "\n");
   } catch {
   }
 }
 function collectAll(opts = {}) {
   const log = opts.log ?? ((m) => console.log(m));
-  const archiveBase = opts.archiveBase ?? join2(resolveDataDir(findRepoRoot()), "archive");
+  const archiveBase = opts.archiveBase ?? join3(resolveDataDir(findRepoRoot()), "archive");
   const sources = opts.sources ?? loadSources();
   const excludedDirs = (opts.excludes ?? loadExcludes()).map(encodeProjectPath);
   const runTs = opts.runTimestamp ?? collectTimestamp();
@@ -1664,9 +1722,16 @@ function acquireLock(lockPath, staleMs = 6 * 60 * 60 * 1e3) {
 // ../core/dist/service.js
 import { spawnSync } from "child_process";
 import { mkdirSync as mkdirSync3, rmSync, writeFileSync as writeFileSync2 } from "fs";
-import { homedir as homedir2, platform as platform3 } from "os";
-import { join as join3 } from "path";
+import { homedir as homedir2, platform as platform3, userInfo } from "os";
+import { join as join4 } from "path";
 var DEFAULT_HOURS = [9, 13, 17, 21];
+function currentUser() {
+  try {
+    return userInfo().username;
+  } catch {
+    return process.env.USER || process.env.LOGNAME || "";
+  }
+}
 var SYSTEMD_COLLECTOR_TIMER = "agent-lens-collect.timer";
 var SYSTEMD_COLLECTOR_SERVICE = "agent-lens-collect.service";
 var SYSTEMD_SERVER_SERVICE = "agent-lens-server.service";
@@ -1691,10 +1756,11 @@ function parseHours(spec) {
 }
 function serverEnv() {
   const env = {};
-  if (process.env.AGENT_LENS_PORT)
-    env.AGENT_LENS_PORT = process.env.AGENT_LENS_PORT;
-  if (process.env.AGENT_LENS_HOST)
-    env.AGENT_LENS_HOST = process.env.AGENT_LENS_HOST;
+  const { port, host, portOrigin, hostOrigin } = resolveServerConfig();
+  if (portOrigin !== "default")
+    env.AGENT_LENS_PORT = String(port);
+  if (hostOrigin !== "default")
+    env.AGENT_LENS_HOST = host;
   return env;
 }
 function onCalendarHours(hours) {
@@ -1807,7 +1873,7 @@ function have(cmd) {
   return r.status === 0 || r.error === void 0;
 }
 function systemdUnitDir() {
-  return join3(process.env.XDG_CONFIG_HOME || join3(homedir2(), ".config"), "systemd", "user");
+  return join4(process.env.XDG_CONFIG_HOME || join4(homedir2(), ".config"), "systemd", "user");
 }
 function linuxInstall(targets, node, cli2, hours) {
   if (!have("systemctl")) {
@@ -1818,11 +1884,11 @@ function linuxInstall(targets, node, cli2, hours) {
   const dir = systemdUnitDir();
   mkdirSync3(dir, { recursive: true });
   if (targets.includes("collector")) {
-    writeFileSync2(join3(dir, SYSTEMD_COLLECTOR_SERVICE), systemdCollectorService(node, cli2));
-    writeFileSync2(join3(dir, SYSTEMD_COLLECTOR_TIMER), systemdCollectorTimer(hours));
+    writeFileSync2(join4(dir, SYSTEMD_COLLECTOR_SERVICE), systemdCollectorService(node, cli2));
+    writeFileSync2(join4(dir, SYSTEMD_COLLECTOR_TIMER), systemdCollectorTimer(hours));
   }
   if (targets.includes("server")) {
-    writeFileSync2(join3(dir, SYSTEMD_SERVER_SERVICE), systemdServerService(node, cli2, serverEnv()));
+    writeFileSync2(join4(dir, SYSTEMD_SERVER_SERVICE), systemdServerService(node, cli2, serverEnv()));
   }
   sh("systemctl", ["--user", "daemon-reload"]);
   if (targets.includes("collector")) {
@@ -1835,8 +1901,9 @@ function linuxInstall(targets, node, cli2, hours) {
     console.log("agent-lens service: installed server daemon");
     sh("systemctl", ["--user", "status", SYSTEMD_SERVER_SERVICE, "--no-pager"]);
   }
-  if (have("loginctl") && !sh("loginctl", ["enable-linger", process.env.USER || ""], true)) {
-    console.log(`agent-lens: could not enable linger automatically; run: sudo loginctl enable-linger ${process.env.USER}`);
+  const user = currentUser();
+  if (user && have("loginctl") && !sh("loginctl", ["enable-linger", user], true)) {
+    console.log(`agent-lens: could not enable linger automatically; run: sudo loginctl enable-linger ${user}`);
   }
 }
 function linuxUninstall(targets) {
@@ -1846,12 +1913,12 @@ function linuxUninstall(targets) {
   if (targets.includes("collector")) {
     sh("systemctl", ["--user", "disable", "--now", SYSTEMD_COLLECTOR_TIMER], true);
     for (const u of [SYSTEMD_COLLECTOR_TIMER, SYSTEMD_COLLECTOR_SERVICE])
-      rmSync(join3(dir, u), { force: true });
+      rmSync(join4(dir, u), { force: true });
     sh("systemctl", ["--user", "reset-failed", SYSTEMD_COLLECTOR_SERVICE], true);
   }
   if (targets.includes("server")) {
     sh("systemctl", ["--user", "disable", "--now", SYSTEMD_SERVER_SERVICE], true);
-    rmSync(join3(dir, SYSTEMD_SERVER_SERVICE), { force: true });
+    rmSync(join4(dir, SYSTEMD_SERVER_SERVICE), { force: true });
     sh("systemctl", ["--user", "reset-failed", SYSTEMD_SERVER_SERVICE], true);
   }
   sh("systemctl", ["--user", "daemon-reload"]);
@@ -1866,7 +1933,7 @@ function linuxStatus(targets) {
     sh("systemctl", ["--user", "status", SYSTEMD_SERVER_SERVICE, "--no-pager"]);
 }
 function launchdPlistPath(label) {
-  return join3(homedir2(), "Library", "LaunchAgents", `${label}.plist`);
+  return join4(homedir2(), "Library", "LaunchAgents", `${label}.plist`);
 }
 function macBootstrap(plist) {
   const uid = typeof process.getuid === "function" ? process.getuid() : 0;
@@ -1880,18 +1947,18 @@ function macBootout(label, plist) {
   rmSync(plist, { force: true });
 }
 function macInstall(targets, node, cli2, hours) {
-  const agents = join3(homedir2(), "Library", "LaunchAgents");
+  const agents = join4(homedir2(), "Library", "LaunchAgents");
   mkdirSync3(agents, { recursive: true });
   const dataDir = resolveDataDir(findRepoRoot());
   if (targets.includes("collector")) {
     const plist = launchdPlistPath(LAUNCHD_COLLECTOR_LABEL);
-    writeFileSync2(plist, launchdCollectorPlist(node, cli2, hours, join3(dataDir, "schedule.log")));
+    writeFileSync2(plist, launchdCollectorPlist(node, cli2, hours, join4(dataDir, "schedule.log")));
     macBootstrap(plist);
     console.log(`agent-lens service: installed collector agent ${LAUNCHD_COLLECTOR_LABEL} (hours ${hours.join(",")})`);
   }
   if (targets.includes("server")) {
     const plist = launchdPlistPath(LAUNCHD_SERVER_LABEL);
-    writeFileSync2(plist, launchdServerPlist(node, cli2, join3(dataDir, "server.log"), serverEnv()));
+    writeFileSync2(plist, launchdServerPlist(node, cli2, join4(dataDir, "server.log"), serverEnv()));
     macBootstrap(plist);
     console.log(`agent-lens service: installed server agent ${LAUNCHD_SERVER_LABEL}`);
   }
@@ -1982,7 +2049,7 @@ function runService(action, params) {
 
 // ../ingest/dist/run.js
 import { readFileSync as readFileSync7, statSync as statSync5, mkdirSync as mkdirSync4, existsSync as existsSync4 } from "fs";
-import { dirname as dirname4, join as join8 } from "path";
+import { dirname as dirname4, join as join9 } from "path";
 
 // ../ingest/dist/db.js
 import Database from "better-sqlite3";
@@ -2038,7 +2105,7 @@ function resetSchema(db) {
 
 // ../ingest/dist/adapters/claude-code.js
 import { readdirSync as readdirSync2 } from "fs";
-import { basename as basename2, join as join4 } from "path";
+import { basename as basename2, join as join5 } from "path";
 function flattenText(content) {
   if (content == null)
     return null;
@@ -2121,7 +2188,7 @@ function recurseJsonl(dir, out) {
     return;
   }
   for (const e of entries) {
-    const p = join4(dir, e.name);
+    const p = join5(dir, e.name);
     if (e.isDirectory())
       recurseJsonl(p, out);
     else if (e.isFile() && e.name.endsWith(".jsonl"))
@@ -2152,12 +2219,12 @@ var ClaudeCodeAdapter = class {
         });
       }
     };
-    addFrom(join4(archiveRoot, "projects"), false);
-    const versionsRoot = join4(archiveRoot, ".versions");
+    addFrom(join5(archiveRoot, "projects"), false);
+    const versionsRoot = join5(archiveRoot, ".versions");
     try {
       for (const ts of readdirSync2(versionsRoot, { withFileTypes: true })) {
         if (ts.isDirectory())
-          addFrom(join4(versionsRoot, ts.name, "projects"), true);
+          addFrom(join5(versionsRoot, ts.name, "projects"), true);
       }
     } catch {
     }
@@ -3584,7 +3651,7 @@ function ingestFile(db, stmts, adapter, file, lines, meta, now2, stats) {
 
 // ../ingest/dist/workflows.js
 import { readdirSync as readdirSync3, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
-import { basename as basename3, join as join5 } from "path";
+import { basename as basename3, join as join6 } from "path";
 
 // ../ingest/dist/redact.js
 import { createHash as createHash4, randomBytes } from "crypto";
@@ -3652,7 +3719,7 @@ function walkSidecars(dir, inWorkflows, out) {
     return;
   }
   for (const e of entries) {
-    const p = join5(dir, e.name);
+    const p = join6(dir, e.name);
     if (e.isDirectory())
       walkSidecars(p, inWorkflows || e.name === "workflows", out);
     else if (e.isFile() && inWorkflows && /^wf_.+\.json$/.test(e.name))
@@ -3661,11 +3728,11 @@ function walkSidecars(dir, inWorkflows, out) {
 }
 function discoverSidecars(sourceArchiveDir) {
   const out = [];
-  walkSidecars(join5(sourceArchiveDir, "projects"), false, out);
+  walkSidecars(join6(sourceArchiveDir, "projects"), false, out);
   try {
-    for (const ts of readdirSync3(join5(sourceArchiveDir, ".versions"), { withFileTypes: true }))
+    for (const ts of readdirSync3(join6(sourceArchiveDir, ".versions"), { withFileTypes: true }))
       if (ts.isDirectory())
-        walkSidecars(join5(sourceArchiveDir, ts.name, "projects"), false, out);
+        walkSidecars(join6(sourceArchiveDir, ts.name, "projects"), false, out);
   } catch {
   }
   return out;
@@ -3783,7 +3850,7 @@ function ingestWorkflowResults(db, sourceArchiveDir, sourceId, excludedDirs, now
 
 // ../ingest/dist/meta.js
 import { readdirSync as readdirSync4, readFileSync as readFileSync5, statSync as statSync3 } from "fs";
-import { basename as basename4, join as join6 } from "path";
+import { basename as basename4, join as join7 } from "path";
 function newMetaStats() {
   return { files: 0, upserted: 0, skipped: 0, malformed: 0 };
 }
@@ -3795,7 +3862,7 @@ function walkMeta(dir, inSubagents, out) {
     return;
   }
   for (const e of entries) {
-    const p = join6(dir, e.name);
+    const p = join7(dir, e.name);
     if (e.isDirectory())
       walkMeta(p, inSubagents || e.name === "subagents", out);
     else if (e.isFile() && inSubagents && /^agent-.+\.meta\.json$/.test(e.name))
@@ -3804,11 +3871,11 @@ function walkMeta(dir, inSubagents, out) {
 }
 function discoverMeta(sourceArchiveDir) {
   const out = [];
-  walkMeta(join6(sourceArchiveDir, "projects"), false, out);
+  walkMeta(join7(sourceArchiveDir, "projects"), false, out);
   try {
-    for (const ts of readdirSync4(join6(sourceArchiveDir, ".versions"), { withFileTypes: true }))
+    for (const ts of readdirSync4(join7(sourceArchiveDir, ".versions"), { withFileTypes: true }))
       if (ts.isDirectory())
-        walkMeta(join6(sourceArchiveDir, ts.name, "projects"), false, out);
+        walkMeta(join7(sourceArchiveDir, ts.name, "projects"), false, out);
   } catch {
   }
   return out;
@@ -3882,7 +3949,7 @@ function ingestSubagentMeta(db, sourceArchiveDir, sourceId, excludedDirs, now2,
 
 // ../ingest/dist/toolResults.js
 import { readdirSync as readdirSync5, readFileSync as readFileSync6, statSync as statSync4 } from "fs";
-import { basename as basename5, join as join7 } from "path";
+import { basename as basename5, join as join8 } from "path";
 function newToolResultStats() {
   return { files: 0, upserted: 0, skipped: 0, malformed: 0 };
 }
@@ -3894,7 +3961,7 @@ function walkResults(dir, inResults, out) {
     return;
   }
   for (const e of entries) {
-    const p = join7(dir, e.name);
+    const p = join8(dir, e.name);
     if (e.isDirectory())
       walkResults(p, inResults || e.name === "tool-results", out);
     else if (e.isFile() && inResults && e.name.endsWith(".txt"))
@@ -3903,11 +3970,11 @@ function walkResults(dir, inResults, out) {
 }
 function discoverResults(sourceArchiveDir) {
   const out = [];
-  walkResults(join7(sourceArchiveDir, "projects"), false, out);
+  walkResults(join8(sourceArchiveDir, "projects"), false, out);
   try {
-    for (const ts of readdirSync5(join7(sourceArchiveDir, ".versions"), { withFileTypes: true }))
+    for (const ts of readdirSync5(join8(sourceArchiveDir, ".versions"), { withFileTypes: true }))
       if (ts.isDirectory())
-        walkResults(join7(sourceArchiveDir, ts.name, "projects"), false, out);
+        walkResults(join8(sourceArchiveDir, ts.name, "projects"), false, out);
   } catch {
   }
   return out;
@@ -3984,8 +4051,8 @@ function parseIngestArgs(argv) {
 function runIngest(argv = process.argv.slice(2)) {
   const args = parseIngestArgs(argv);
   const dataDir = resolveDataDir(findRepoRoot());
-  const archiveRoot = args.archive || process.env.AGENT_LENS_ARCHIVE || join8(dataDir, "archive");
-  const dbPath = args.db || process.env.AGENT_LENS_DB || join8(dataDir, "agent-lens.db");
+  const archiveRoot = args.archive || process.env.AGENT_LENS_ARCHIVE || join9(dataDir, "archive");
+  const { path: dbPath } = resolveDbPath(args.db);
   if (!existsSync4(archiveRoot)) {
     console.error(`agent-lens-ingest: archive not found: ${archiveRoot} (run 'agent-lens collect' first)`);
     process.exit(1);
@@ -4023,7 +4090,7 @@ function runIngest(argv = process.argv.slice(2)) {
     }
     stmts.insAgent.run(adapter.agentId, adapter.agentName);
     stmts.insSource.run({ id: source.label, label: source.label, agent_id: adapter.agentId, config_dir: source.configDir });
-    let files = adapter.discover(join8(archiveRoot, source.label), source.label);
+    let files = adapter.discover(join9(archiveRoot, source.label), source.label);
     if (excludedDirs.length)
       files = files.filter((f) => !isExcludedArchivePath(f.path, excludedDirs));
     files.sort((a, b) => Number(a.isVersion) - Number(b.isVersion));
@@ -4055,9 +4122,9 @@ function runIngest(argv = process.argv.slice(2)) {
       ingestFile(db, stmts, adapter, file, lines, { size: st.size, mtimeMs, hash: hash2 }, now2, stats);
       dirty.add(file.sessionId);
     }
-    ingestWorkflowResults(db, join8(archiveRoot, source.label), source.label, excludedDirs, now2, wfStats, args.full);
-    ingestSubagentMeta(db, join8(archiveRoot, source.label), source.label, excludedDirs, now2, metaStats, args.full);
-    ingestToolResults(db, join8(archiveRoot, source.label), excludedDirs, now2, trStats, args.full);
+    ingestWorkflowResults(db, join9(archiveRoot, source.label), source.label, excludedDirs, now2, wfStats, args.full);
+    ingestSubagentMeta(db, join9(archiveRoot, source.label), source.label, excludedDirs, now2, metaStats, args.full);
+    ingestToolResults(db, join9(archiveRoot, source.label), excludedDirs, now2, trStats, args.full);
   }
   const expanded = rebuildDerived(db, args.full ? null : dirty);
   const classified = classify(db, args.full ? null : expanded);
@@ -4095,8 +4162,7 @@ function runMetrics(argv = process.argv.slice(2)) {
   for (let i = 0; i < argv.length; i++)
     if (argv[i] === "--db")
       dbArg = argv[++i] ?? "";
-  const dataDir = resolveDataDir(findRepoRoot());
-  const dbPath = dbArg || process.env.AGENT_LENS_DB || join8(dataDir, "agent-lens.db");
+  const { path: dbPath } = resolveDbPath(dbArg);
   if (!existsSync4(dbPath)) {
     console.error(`agent-lens-metrics: db not found: ${dbPath} (run ingest first)`);
     process.exit(1);
@@ -4111,7 +4177,7 @@ function runMetrics(argv = process.argv.slice(2)) {
 
 // ../server/dist/run.js
 import { existsSync as existsSync7 } from "fs";
-import { dirname as dirname5, join as join10 } from "path";
+import { dirname as dirname5, join as join11 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // ../server/dist/db.js
@@ -4967,7 +5033,7 @@ function dashboardBreakdowns(db, f) {
 
 // ../server/dist/refresh.js
 import { existsSync as existsSync5, mkdirSync as mkdirSync5 } from "fs";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 function originAllowed(origin) {
   if (!origin)
     return true;
@@ -4988,12 +5054,12 @@ function writeBlocked(headers) {
 }
 function runRefresh() {
   const dataDir = resolveDataDir(findRepoRoot());
-  const lock = acquireLock(join9(dataDir, ".agent-lens.lock"));
+  const lock = acquireLock(join10(dataDir, ".agent-lens.lock"));
   if (!lock)
     return null;
   try {
     const collected = collectAll();
-    const archiveRoot = process.env.AGENT_LENS_ARCHIVE || join9(dataDir, "archive");
+    const archiveRoot = process.env.AGENT_LENS_ARCHIVE || join10(dataDir, "archive");
     if (!existsSync5(archiveRoot))
       mkdirSync5(archiveRoot, { recursive: true });
     runIngest([]);
@@ -5309,12 +5375,11 @@ async function createApp(db, opts = {}) {
 }
 
 // ../server/dist/run.js
-async function startServer() {
+async function startServer(overrides = {}) {
   const here = dirname5(fileURLToPath2(import.meta.url));
   const repoRoot = findRepoRoot(here);
-  const dbPath = process.env.AGENT_LENS_DB || join10(resolveDataDir(repoRoot), "agent-lens.db");
-  const host = process.env.AGENT_LENS_HOST || "127.0.0.1";
-  const port = Number(process.env.AGENT_LENS_PORT || 4477);
+  const { path: dbPath } = resolveDbPath(overrides.db);
+  const { host, port } = resolveServerConfig({ port: overrides.port, host: overrides.host });
   const webDist = resolveWebDist(here, repoRoot);
   if (host !== "127.0.0.1" && host !== "localhost" && !process.env.AGENT_LENS_ALLOW_NONLOCAL) {
     console.error(`agent-lens-server: refusing to bind non-loopback host '${host}' (privacy). Set AGENT_LENS_ALLOW_NONLOCAL=1 to override.`);
@@ -5324,7 +5389,7 @@ async function startServer() {
     console.error(`agent-lens-server: db not found: ${dbPath} (run ingest first)`);
     process.exit(1);
   }
-  const triageDbPath = process.env.AGENT_LENS_TRIAGE_DB || join10(dirname5(dbPath), "triage.db");
+  const triageDbPath = process.env.AGENT_LENS_TRIAGE_DB || join11(dirname5(dbPath), "triage.db");
   const db = openReadonly(dbPath);
   const enforceLoopbackHost = host === "127.0.0.1" || host === "localhost";
   const app = await createApp(db, { webDist, triageDbPath, enforceLoopbackHost });
@@ -5341,11 +5406,11 @@ async function startServer() {
 
 // src/watch.ts
 import { existsSync as existsSync8 } from "fs";
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 import chokidar from "chokidar";
 async function runWatch(opts = {}) {
   const sources = loadSources();
-  const lockPath = join11(resolveDataDir(findRepoRoot()), ".agent-lens.lock");
+  const lockPath = join12(resolveDataDir(findRepoRoot()), ".agent-lens.lock");
   let running = false;
   let pending = false;
   const cycle = () => {
@@ -5378,7 +5443,7 @@ async function runWatch(opts = {}) {
     }
   };
   cycle();
-  const watchPaths = sources.map((s) => join11(s.configDir, "projects")).filter((p) => existsSync8(p));
+  const watchPaths = sources.map((s) => join12(s.configDir, "projects")).filter((p) => existsSync8(p));
   if (watchPaths.length === 0) {
     console.error("agent-lens watch: no source 'projects' directories found \u2014 nothing to watch");
   }
@@ -5406,14 +5471,14 @@ async function runWatch(opts = {}) {
 // src/index.ts
 function version() {
   try {
-    const pkg = JSON.parse(readFileSync8(join12(dirname6(fileURLToPath3(import.meta.url)), "../package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync8(join13(dirname6(fileURLToPath3(import.meta.url)), "../package.json"), "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
   }
 }
 function withLock(fn) {
-  const lockPath = join12(resolveDataDir(findRepoRoot()), ".agent-lens.lock");
+  const lockPath = join13(resolveDataDir(findRepoRoot()), ".agent-lens.lock");
   const lock = acquireLock(lockPath);
   if (!lock) {
     console.error("agent-lens: another collect/ingest run is in progress \u2014 skipping");
@@ -5435,24 +5500,29 @@ cli.command("collect", "Copy new session traces into the local archive").option(
     if (opts.thenIngest) runIngest([]);
   });
 });
-cli.command("ingest", "Build/update the SQLite projection from the archive").option("--full", "Ignore incremental state and re-read every file").option("--db <path>", "SQLite DB path").option("--archive <path>", "Archive directory").action((opts) => {
+cli.command("ingest", "Build/update the SQLite projection from the archive").option("--full", "Ignore incremental state and re-read every file").option("--db <path>", "SQLite DB path (overrides AGENT_LENS_DB / config db)").option("--archive <path>", "Archive directory").action((opts) => {
   const argv = [];
   if (opts.full) argv.push("--full");
   if (opts.db) argv.push("--db", opts.db);
   if (opts.archive) argv.push("--archive", opts.archive);
   withLock(() => runIngest(argv));
 });
-cli.command("serve", "Serve the web UI + read-only API on 127.0.0.1").action(async () => {
-  await startServer();
+cli.command("serve", "Serve the web UI + read-only API on 127.0.0.1").option("--port <n>", "HTTP port (overrides AGENT_LENS_PORT / config server.port; default 4477)").option("--host <host>", "Bind host (overrides AGENT_LENS_HOST / config server.host; loopback only unless AGENT_LENS_ALLOW_NONLOCAL=1)").option("--db <path>", "SQLite DB path (overrides AGENT_LENS_DB / config db)").action(async (opts) => {
+  try {
+    await startServer({ port: opts.port, host: opts.host, db: opts.db });
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
 });
 cli.command("watch", "Watch sources and collect + ingest on change (resident process)").option("--interval <sec>", "Also run on a fixed interval (seconds)").option("--poll", "Use polling \u2014 for network filesystems where fs events don't fire").action(async (opts) => {
   await runWatch({ intervalSec: opts.interval ? Number(opts.interval) : void 0, poll: !!opts.poll });
 });
-cli.command("metrics", "Re-run classification over an already-ingested DB").option("--db <path>", "SQLite DB path").action((opts) => {
+cli.command("metrics", "Re-run classification over an already-ingested DB").option("--db <path>", "SQLite DB path (overrides AGENT_LENS_DB / config db)").action((opts) => {
   runMetrics(opts.db ? ["--db", opts.db] : []);
 });
-cli.command("export <sessionId>", "Write a session to a shareable Markdown file (redacted by default)").option("--out <file>", "Write to this file (default: stdout)").option("--level <level>", "Redaction level: secrets (default) | structure").option("--no-redact", "Verbatim, UNREDACTED output (opt-out)").option("--db <path>", "SQLite DB path").action((sessionId, opts) => {
-  const dbPath = opts.db || process.env.AGENT_LENS_DB || join12(resolveDataDir(findRepoRoot()), "agent-lens.db");
+cli.command("export <sessionId>", "Write a session to a shareable Markdown file (redacted by default)").option("--out <file>", "Write to this file (default: stdout)").option("--level <level>", "Redaction level: secrets (default) | structure").option("--no-redact", "Verbatim, UNREDACTED output (opt-out)").option("--db <path>", "SQLite DB path (overrides AGENT_LENS_DB / config db)").action((sessionId, opts) => {
+  const { path: dbPath } = resolveDbPath(opts.db);
   if (!existsSync9(dbPath)) {
     console.error(`agent-lens: db not found: ${dbPath} (run ingest first)`);
     process.exit(1);
@@ -5478,6 +5548,39 @@ cli.command(
   const hours = action === "install" ? parseHours(opts.times) : void 0;
   runService(action, { cliEntry: fileURLToPath3(import.meta.url), hours, targets });
 });
+cli.command("config", "Show the effective configuration (sources, paths, server) and where each value came from").action(() => {
+  const repoRoot = findRepoRoot();
+  const dataDir = resolveDataDir(repoRoot);
+  const configFile = resolveConfigFile(repoRoot, dataDir);
+  let server;
+  try {
+    server = resolveServerConfig();
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  const { port, host, portOrigin, hostOrigin } = server;
+  const { path: dbPath, origin: dbOrigin } = resolveDbPath();
+  const archive = process.env.AGENT_LENS_ARCHIVE || join13(dataDir, "archive");
+  const triageDb = process.env.AGENT_LENS_TRIAGE_DB || join13(dirname6(dbPath), "triage.db");
+  const keepDays = process.env.AGENT_LENS_VERSIONS_KEEP_DAYS || "90";
+  const keepOrigin = process.env.AGENT_LENS_VERSIONS_KEEP_DAYS ? "env" : "default";
+  console.log("agent-lens config (precedence: flag > env > config file > default)\n");
+  console.log("Paths");
+  console.log(`  config file      ${configFile ?? "(none \u2014 using built-in default source)"}`);
+  console.log(`  data dir         ${dataDir}${process.env.AGENT_LENS_DATA ? "  [env]" : ""}`);
+  console.log(`  archive          ${archive}${process.env.AGENT_LENS_ARCHIVE ? "  [env]" : ""}`);
+  console.log(`  db               ${dbPath}  [${dbOrigin}]`);
+  console.log(`  triage db        ${triageDb}${process.env.AGENT_LENS_TRIAGE_DB ? "  [env]" : ""}`);
+  console.log("\nServer");
+  console.log(`  host             ${host}  [${hostOrigin}]`);
+  console.log(`  port             ${port}  [${portOrigin}]`);
+  console.log(`  non-local bind   ${process.env.AGENT_LENS_ALLOW_NONLOCAL ? "allowed (AGENT_LENS_ALLOW_NONLOCAL)" : "blocked (loopback only)"}`);
+  console.log("\nRetention");
+  console.log(`  .versions keep   ${keepDays} day(s)  [${keepOrigin}]`);
+  console.log("\nSources");
+  for (const s of loadSources()) console.log(`  ${s.label.padEnd(14)} ${s.configDir}  (${s.agent})`);
+});
 cli.help();
 cli.version(version());
 cli.parse();