@faithfulalabi/agent-lens 0.1.0

package/dist/src/cli/commands/prune.js

@@ -0,0 +1,159 @@
+import { lstatSync, rmSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { sep } from 'node:path';
+import { assertNotUnderRoot, assertUnderRoot, buildDoctorReport, DATA_DIR_LABEL, discover, resolveDataDir, resolveTranscriptRoot, TRANSCRIPT_ROOT_LABEL, } from '../../archive/index.js';
+import { classifyCorpusPath, rowIdOf, sessionDirOf } from '../../corpus/paths.js';
+import { EXIT_INCOMPLETE, EXIT_OK, parseStringFlag } from './archive.js';
+import { COVERAGE_GAP_STATEMENT, DURABILITY_STATEMENT, formatRetention } from './doctor.js';
+const KNOWN_FLAGS = new Set(['--dataDir', '--transcriptRoot', '--settingsPath']);
+const WHOLE_ARCHIVE_WORD = 'delete';
+function diskPathOf(entry) {
+    return entry.sealed ? `${entry.archivePath}.zst` : entry.archivePath;
+}
+function bytesOf(path) {
+    try {
+        return lstatSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+export function parsePruneArgs(args) {
+    let id;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg.startsWith('-')) {
+            const eq = arg.indexOf('=');
+            const name = eq === -1 ? arg : arg.slice(0, eq);
+            if (!KNOWN_FLAGS.has(name)) {
+                return {
+                    ok: false,
+                    message: `unrecognised option ${arg} — prune takes [session-id] ` +
+                        '[--dataDir=…] [--transcriptRoot=…] [--settingsPath=…] and nothing else',
+                };
+            }
+            if (eq === -1)
+                i += 1;
+            continue;
+        }
+        if (id !== undefined) {
+            return {
+                ok: false,
+                message: `unexpected argument ${arg} — prune takes at most one session id`,
+            };
+        }
+        id = arg;
+    }
+    return id === undefined ? { ok: true } : { ok: true, id };
+}
+export function resolvePruneTarget(report, id) {
+    if (id === undefined) {
+        return {
+            ok: true,
+            target: {
+                label: 'the whole archive',
+                confirmWord: WHOLE_ARCHIVE_WORD,
+                paths: [report.archiveRoot],
+                files: report.bytes.hotFiles + report.bytes.sealedFiles,
+                bytes: report.bytes.totalBytes,
+                archiveOnly: report.coverage.archiveOnly,
+            },
+        };
+    }
+    const entries = discover(report.sourceRoot, report.archiveRoot);
+    const kindOf = (entry) => classifyCorpusPath(entry.relPath);
+    const match = entries.find((e) => kindOf(e) === 'session' && rowIdOf(e.relPath) === id);
+    if (match === undefined) {
+        const sidecar = entries.find((e) => kindOf(e) === 'sidecar' && rowIdOf(e.relPath) === id);
+        if (sidecar !== undefined) {
+            const parent = entries.find((e) => kindOf(e) === 'session' &&
+                sidecar.archivePath.startsWith(sessionDirOf(e.archivePath) + sep));
+            const named = parent === undefined ? 'its parent session' : `session ${rowIdOf(parent.relPath)}`;
+            return {
+                ok: false,
+                message: `${id} is a sub-agent transcript — prune ${named}, which removes it too`,
+            };
+        }
+        return { ok: false, message: `no archived session ${id} under ${report.archiveRoot}` };
+    }
+    const dir = sessionDirOf(match.archivePath);
+    const owned = entries.filter((e) => e.presence !== 'source-only' &&
+        (e.archivePath === match.archivePath || e.archivePath.startsWith(dir + sep)));
+    return {
+        ok: true,
+        target: {
+            label: `session ${id}`,
+            confirmWord: id,
+            paths: [diskPathOf(match), dir],
+            files: owned.length,
+            bytes: owned.reduce((sum, e) => sum + bytesOf(diskPathOf(e)), 0),
+            archiveOnly: owned.filter((e) => e.presence === 'archive-only').length,
+        },
+    };
+}
+export function formatPruneConfirm(report, target) {
+    const lines = [
+        'agent-lens prune — permanent, immediate, and there is no undo.',
+        '',
+        `  archive     ${report.archiveRoot}`,
+        `  deleting    ${target.label} — ${target.files} files, ${target.bytes} bytes`,
+    ];
+    for (const path of target.paths)
+        lines.push(`                ${path}`);
+    lines.push(`  of those    ${target.archiveOnly} have no live source left — the archive is the only copy left`, '', DURABILITY_STATEMENT, COVERAGE_GAP_STATEMENT, '', 'Claude Code deletes its own transcripts on a rolling window and agent-lens does not', `control it: ${formatRetention(report.retention)}. Everything past that window exists`, 'only here. No soft-delete, no trash, no recovery.', '', `Type \`${target.confirmWord}\` to confirm; anything else aborts.`);
+    return lines.join('\n');
+}
+async function readConfirmLine() {
+    const rl = createInterface({ input: process.stdin, terminal: false });
+    try {
+        const { value, done } = await rl[Symbol.asyncIterator]().next();
+        return done === true ? '' : value;
+    }
+    finally {
+        rl.close();
+        process.stdin.pause();
+    }
+}
+export async function prune(args = [], options = {}) {
+    try {
+        const parsed = parsePruneArgs(args);
+        if (!parsed.ok) {
+            console.error(`agent-lens prune: ${parsed.message}`);
+            return EXIT_INCOMPLETE;
+        }
+        const dataDirFlag = parseStringFlag(args, 'dataDir');
+        const transcriptRootFlag = parseStringFlag(args, 'transcriptRoot');
+        const report = buildDoctorReport({
+            dataDir: dataDirFlag,
+            transcriptRoot: transcriptRootFlag,
+            settingsPath: parseStringFlag(args, 'settingsPath'),
+        });
+        const resolved = resolvePruneTarget(report, parsed.id);
+        if (!resolved.ok) {
+            console.error(`agent-lens prune: ${resolved.message}`);
+            return EXIT_INCOMPLETE;
+        }
+        const { target } = resolved;
+        const dataDir = resolveDataDir(dataDirFlag);
+        const transcriptRoot = resolveTranscriptRoot(transcriptRootFlag);
+        for (const path of target.paths) {
+            assertUnderRoot(path, dataDir, DATA_DIR_LABEL);
+            assertNotUnderRoot(path, transcriptRoot, TRANSCRIPT_ROOT_LABEL);
+        }
+        console.log(formatPruneConfirm(report, target));
+        const answer = await (options.confirm ?? readConfirmLine)();
+        if (answer !== target.confirmWord) {
+            console.log('agent-lens prune: declined — nothing was deleted');
+            return EXIT_OK;
+        }
+        for (const path of target.paths)
+            rmSync(path, { recursive: true, force: true });
+        console.log(`agent-lens prune: deleted ${target.label} — ${target.files} files, ${target.bytes} bytes`);
+        console.log('  cache.db is untouched — `agent-lens rebuild` clears what is now gone');
+        return EXIT_OK;
+    }
+    catch (error) {
+        console.error(`agent-lens prune: ${String(error.message ?? error)}`);
+        return EXIT_INCOMPLETE;
+    }
+}

package/dist/src/cli/commands/rebuild.js

@@ -0,0 +1,98 @@
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { acquireLock, resolveArchiveRoot, resolveDataDir, resolveTranscriptRoot, } from '../../archive/index.js';
+import { createArchiveReader } from '../../archive/read.js';
+import { createProjectionEnv } from '../../corpus/env.js';
+import { ensureProjectedFold } from '../../db/freshness.js';
+import { CACHE_DB_FILE, CACHE_LOCK_FILE, DbLockedError, openDb } from '../../db/open.js';
+import { readEventCount } from '../../db/read.js';
+import { deleteSessionProjection, projectSession } from '../../db/write.js';
+import { EXIT_INCOMPLETE, EXIT_OK, parseStringFlag } from './archive.js';
+export function parseSessionId(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg.startsWith('-')) {
+            if (arg === '--dataDir' || arg === '--transcriptRoot')
+                i += 1;
+            continue;
+        }
+        return arg;
+    }
+    return undefined;
+}
+function rebuildCache(dataDir) {
+    const lockPath = join(dataDir, CACHE_LOCK_FILE);
+    const lock = acquireLock(dataDir, undefined, lockPath);
+    if (lock.state.state === 'held') {
+        const pid = lock.state.holder_pid ?? 'unknown';
+        console.error(`agent-lens is already running (pid ${pid}) — stop it before rebuilding the cache`);
+        return EXIT_INCOMPLETE;
+    }
+    try {
+        const cachePath = join(dataDir, CACHE_DB_FILE);
+        const removed = [];
+        for (const suffix of ['', '-wal', '-shm']) {
+            const target = cachePath + suffix;
+            if (existsSync(target))
+                removed.push(target);
+            rmSync(target, { force: true });
+        }
+        if (removed.length === 0) {
+            console.log(`agent-lens rebuild: no cache at ${cachePath} — the next start builds one`);
+            return EXIT_OK;
+        }
+        console.log(`agent-lens rebuild: removed ${removed.length} file(s)`);
+        for (const path of removed)
+            console.log(`  ${path}`);
+        console.log('  the next `agent-lens start` re-indexes the archive and reprojects on read');
+        return EXIT_OK;
+    }
+    finally {
+        lock.release();
+    }
+}
+function rebuildSession(dataDir, transcriptRoot, id) {
+    const opened = openDb({ dataDir });
+    try {
+        const env = createProjectionEnv(createArchiveReader(), {
+            archiveRoot: resolveArchiveRoot(dataDir),
+            transcriptRoot,
+        });
+        const started = Date.now();
+        const gate = ensureProjectedFold(opened.db, id, env);
+        if (gate.outcome === 'unindexed') {
+            console.error(`agent-lens rebuild: ${id} is not indexed — run \`agent-lens start\` first`);
+            return EXIT_INCOMPLETE;
+        }
+        if (gate.outcome === 'failed' || gate.fold === undefined) {
+            console.error(`agent-lens rebuild: ${id} has no readable archived bytes`);
+            return EXIT_INCOMPLETE;
+        }
+        if (gate.outcome === 'hit') {
+            deleteSessionProjection(opened.db, id);
+            projectSession(opened.db, id, env, gate.fold);
+        }
+        const events = readEventCount(opened.db, id);
+        console.log(`agent-lens rebuild: ${id} — ${events} events, took_ms ${Date.now() - started}`);
+        return EXIT_OK;
+    }
+    finally {
+        opened.close();
+    }
+}
+export async function rebuild(args = []) {
+    try {
+        const dataDir = resolveDataDir(parseStringFlag(args, 'dataDir'));
+        const transcriptRoot = resolveTranscriptRoot(parseStringFlag(args, 'transcriptRoot'));
+        const id = parseSessionId(args);
+        return id === undefined ? rebuildCache(dataDir) : rebuildSession(dataDir, transcriptRoot, id);
+    }
+    catch (error) {
+        if (error instanceof DbLockedError) {
+            console.error(`${error.message} — stop it, or reproject from the running UI instead`);
+            return EXIT_INCOMPLETE;
+        }
+        console.error(`agent-lens rebuild: ${String(error.message ?? error)}`);
+        return EXIT_INCOMPLETE;
+    }
+}

package/dist/src/cli/commands/schedule.js

@@ -0,0 +1,325 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertNotUnderRoot, lstatSafe, resolveCronLogPath, resolveDataDir, resolvePlistPath, resolveScheduleWrapperPath, resolveTranscriptRoot, TRANSCRIPT_ROOT_LABEL, } from '../../archive/paths.js';
+import { parseStringFlag } from './archive.js';
+export const SCHEDULE_LABEL = 'com.agent-lens.archive';
+export const LEGACY_LABEL = 'com.faithful.agent-lens.archive';
+const START_INTERVAL_SECONDS = 900;
+export const CRON_STAMP_FORMAT = '+%Y-%m-%dT%H:%M:%S%z';
+export const WAKE_TIME_CAVEAT = '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';
+const ACTIONS = 'install | status | disable';
+const NON_MACOS_POINTER = 'the recurring job uses launchd, which is macOS-only. Elsewhere, run `agent-lens archive` ' +
+    'every ~15 minutes yourself — a systemd timer or cron entry — per the README section ' +
+    '"Keeping the archive current".';
+function realLaunchctl(args) {
+    const result = spawnSync('launchctl', args, { encoding: 'utf8' });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.error === undefined ? (result.stderr ?? '') : String(result.error.message),
+    };
+}
+function realDeps() {
+    return {
+        platform: process.platform,
+        execPath: process.execPath,
+        homeDir: homedir(),
+        uid: process.getuid?.() ?? 0,
+        moduleUrl: import.meta.url,
+        launchctl: realLaunchctl,
+        now: Date.now,
+    };
+}
+export function parseScheduleAction(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg.startsWith('-')) {
+            if (arg === '--dataDir')
+                i += 1;
+            continue;
+        }
+        return arg;
+    }
+    return undefined;
+}
+function resolvePackageRoot(fromDir) {
+    let dir = fromDir;
+    for (;;) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error(`no package.json above ${fromDir}; cannot locate the package root`);
+        }
+        dir = parent;
+    }
+}
+export function resolveArchiveInvocation(moduleUrl) {
+    const modulePath = fileURLToPath(moduleUrl);
+    return {
+        packageRoot: resolvePackageRoot(dirname(modulePath)),
+        kind: modulePath.endsWith('.ts') ? 'source' : 'built',
+    };
+}
+function shQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function buildWrapperScript(opts) {
+    const { kind, packageRoot } = opts.invocation;
+    const entry = kind === 'source' ? '$ROOT/src/cli/index.ts' : '$ROOT/bin/agent-lens.js';
+    const run = kind === 'source'
+        ? '"$NODE" --import tsx "$ROOT/src/cli/index.ts" archive --dataDir "$DATA_DIR"'
+        : '"$NODE" "$ROOT/bin/agent-lens.js" archive --dataDir "$DATA_DIR"';
+    return `#!/bin/sh
+# agent-lens archive — unattended pass, invoked by the launchd agent
+# ${SCHEDULE_LABEL} every ${START_INTERVAL_SECONDS / 60} minutes.
+#
+# GENERATED by \`agent-lens schedule\` — do not edit. Turning the job on again
+# rewrites this file in full, which is what keeps it current with the package
+# that shipped it.
+#
+# Coverage is wake-time-bounded: ${WAKE_TIME_CAVEAT}.
+#
+# Exit codes are the archive command's own and are load-bearing:
+#   0 = clean pass       1 = usage error / crash       3 = archive-side errors
+#   2 is RESERVED product-wide and must never appear here.
+set -u
+
+NODE=${shQuote(opts.nodePath)}
+ROOT=${shQuote(packageRoot)}
+DATA_DIR=${shQuote(opts.dataDir)}
+LOG=${shQuote(opts.cronLogPath)}
+MAX_LINES=5000
+
+# launchd hands over a minimal PATH. The node binary is addressed absolutely so
+# the pass cannot hit an \`env: node\` lookup failure, and the export keeps
+# anything the pass shells out to on a sane PATH too.
+PATH="$(dirname "$NODE"):/usr/bin:/bin:/usr/sbin:/sbin"
+export PATH
+
+mkdir -p "$(dirname "$LOG")"
+
+stamp() { date "${CRON_STAMP_FORMAT}"; }
+say() { printf '%s %s\\n' "$(stamp)" "$1" >>"$LOG"; }
+
+# Preconditions are logged loudly rather than failing silently: a job that
+# quietly does nothing is indistinguishable from one that is working.
+[ -d "$ROOT" ]              || { say "FATAL package root missing: $ROOT"; exit 1; }
+[ -x "$NODE" ]              || { say "FATAL node missing: $NODE"; exit 1; }
+[ -e "${entry}" ] || { say "FATAL entry missing: ${entry}"; exit 1; }
+[ -d "$ROOT/node_modules" ] || { say "FATAL node_modules missing — run npm install in $ROOT"; exit 1; }
+
+cd "$ROOT" || { say "FATAL cannot cd to $ROOT"; exit 1; }
+
+OUT=$(${run} 2>&1)
+CODE=$?
+
+case "$CODE" in
+  0) say "ok   $OUT" ;;
+  3) say "ERR3 archive-side errors — $OUT" ;;
+  2) say "BUG  exit 2 is reserved product-wide and must never come from archive — $OUT" ;;
+  *) say "ERR$CODE $OUT" ;;
+esac
+
+# Bounded log: keep the most recent MAX_LINES so months of 15-minute passes
+# cannot fill the disk the archive depends on.
+if [ -f "$LOG" ]; then
+  LINES=$(wc -l <"$LOG" 2>/dev/null || echo 0)
+  if [ "$LINES" -gt "$MAX_LINES" ]; then
+    tail -n "$MAX_LINES" "$LOG" >"$LOG.tmp" 2>/dev/null && mv "$LOG.tmp" "$LOG"
+  fi
+fi
+
+exit "$CODE"
+`;
+}
+function xmlEscape(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function buildPlist(opts) {
+    const outLog = xmlEscape(join(opts.dataDir, 'logs', 'launchd.out.log'));
+    const errLog = xmlEscape(join(opts.dataDir, 'logs', 'launchd.err.log'));
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SCHEDULE_LABEL}</string>
+
+  <!-- Coverage is wake-time-bounded: ${xmlEscape(WAKE_TIME_CAVEAT)}. -->
+
+  <!-- /bin/sh rather than the script directly: launchd exec failures are then
+       reported against a known-good binary, so a broken shebang or a lost
+       +x bit shows up as a script error instead of a silent no-op. -->
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>${xmlEscape(opts.wrapperPath)}</string>
+  </array>
+
+  <key>StartInterval</key>
+  <integer>${START_INTERVAL_SECONDS}</integer>
+
+  <!-- Catch up immediately at login rather than waiting out the first interval:
+       the gap after a reboot is exactly when expiry is most likely to have run. -->
+  <key>RunAtLoad</key>
+  <true/>
+
+  <!-- launchd-level failures ONLY (exec errors, Full Disk Access denials).
+       The pass's own results go to logs/cron.log via the wrapper. -->
+  <key>StandardOutPath</key>
+  <string>${outLog}</string>
+  <key>StandardErrorPath</key>
+  <string>${errLog}</string>
+
+  <key>ProcessType</key>
+  <string>Background</string>
+
+  <!-- Deliberately NOT set: KeepAlive. This is a periodic batch job, not a
+       daemon; KeepAlive would restart it in a tight loop after every exit. -->
+</dict>
+</plist>
+`;
+}
+function ensureDirOutsideCorpus(dir, mode, transcriptRoot) {
+    assertNotUnderRoot(dir, transcriptRoot, TRANSCRIPT_ROOT_LABEL);
+    mkdirSync(dir, { recursive: true, mode });
+}
+function atomicWrite(path, text, mode, transcriptRoot) {
+    assertNotUnderRoot(path, transcriptRoot, TRANSCRIPT_ROOT_LABEL);
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, text, { mode });
+    chmodSync(tmp, mode);
+    renameSync(tmp, path);
+}
+function removeIfPresent(path, transcriptRoot) {
+    if (lstatSafe(path) === undefined)
+        return false;
+    assertNotUnderRoot(path, transcriptRoot, TRANSCRIPT_ROOT_LABEL);
+    unlinkSync(path);
+    return true;
+}
+function gui(deps, label) {
+    return `gui/${deps.uid}/${label}`;
+}
+function install(dataDirFlag, deps) {
+    if (deps.platform !== 'darwin') {
+        console.error(`agent-lens schedule: nothing was set up — ${NON_MACOS_POINTER}`);
+        return 1;
+    }
+    const dataDir = resolveDataDir(dataDirFlag);
+    const transcriptRoot = resolveTranscriptRoot();
+    const wrapperPath = resolveScheduleWrapperPath(dataDir);
+    const plistPath = resolvePlistPath(SCHEDULE_LABEL, deps.homeDir);
+    const cronLogPath = resolveCronLogPath(dataDir);
+    const lines = [];
+    const legacyPlist = resolvePlistPath(LEGACY_LABEL, deps.homeDir);
+    const legacyWrapper = join(deps.homeDir, '.agent-lens', 'archive-cron.sh');
+    if (lstatSafe(legacyPlist) !== undefined || lstatSafe(legacyWrapper) !== undefined) {
+        deps.launchctl(['bootout', gui(deps, LEGACY_LABEL)]);
+        removeIfPresent(legacyPlist, transcriptRoot);
+        removeIfPresent(legacyWrapper, transcriptRoot);
+        lines.push(`migrated the legacy ${LEGACY_LABEL} job out — one job, one label`);
+    }
+    const invocation = resolveArchiveInvocation(deps.moduleUrl);
+    ensureDirOutsideCorpus(dirname(wrapperPath), 0o700, transcriptRoot);
+    ensureDirOutsideCorpus(dirname(cronLogPath), 0o700, transcriptRoot);
+    ensureDirOutsideCorpus(dirname(plistPath), 0o755, transcriptRoot);
+    atomicWrite(wrapperPath, buildWrapperScript({ nodePath: deps.execPath, invocation, dataDir, cronLogPath }), 0o700, transcriptRoot);
+    atomicWrite(plistPath, buildPlist({ wrapperPath, dataDir }), 0o644, transcriptRoot);
+    deps.launchctl(['bootout', gui(deps, SCHEDULE_LABEL)]);
+    const bootstrap = deps.launchctl(['bootstrap', `gui/${deps.uid}`, plistPath]);
+    if (bootstrap.status !== 0) {
+        deps.launchctl(['unload', '-w', plistPath]);
+        const load = deps.launchctl(['load', '-w', plistPath]);
+        if (load.status !== 0) {
+            const detail = (load.stderr || bootstrap.stderr).trim();
+            console.error(`agent-lens schedule: launchctl could not load the job — ${detail}`);
+            return 1;
+        }
+    }
+    lines.push(`recurring archive job on — label ${SCHEDULE_LABEL}, every ` +
+        `${START_INTERVAL_SECONDS / 60} minutes (${invocation.kind} layout)`, `  wrapper  ${wrapperPath}`, `  passes   ${cronLogPath}`, `note: ${WAKE_TIME_CAVEAT}`);
+    console.log(lines.join('\n'));
+    return 0;
+}
+async function status(dataDirFlag, deps) {
+    if (deps.platform !== 'darwin') {
+        console.log(`agent-lens schedule: ${NON_MACOS_POINTER}`);
+        console.log(`note: ${WAKE_TIME_CAVEAT}`);
+        return 0;
+    }
+    const plistPath = resolvePlistPath(SCHEDULE_LABEL, deps.homeDir);
+    const lines = [];
+    if (lstatSafe(plistPath)?.isFile() === true) {
+        lines.push(`recurring archive job: installed — ${plistPath}`);
+        const print = deps.launchctl(['print', gui(deps, SCHEDULE_LABEL)]);
+        lines.push(print.status === 0
+            ? `  loaded in launchd (${SCHEDULE_LABEL})`
+            : `  NOT loaded in launchd — run \`agent-lens schedule install\` to load it`);
+    }
+    else {
+        lines.push('recurring archive job: not installed');
+        lines.push('  turn it on with: agent-lens schedule install');
+    }
+    const [{ formatLastPassSection }, { readCronLogStatus }] = await Promise.all([
+        import('./doctor.js'),
+        import('../../archive/cron-log.js'),
+    ]);
+    lines.push(...formatLastPassSection(readCronLogStatus(dataDirFlag), deps.now()));
+    lines.push('', `note: ${WAKE_TIME_CAVEAT}`);
+    console.log(lines.join('\n'));
+    return 0;
+}
+function disable(dataDirFlag, deps) {
+    if (deps.platform !== 'darwin') {
+        console.error(`agent-lens schedule: nothing was removed — ${NON_MACOS_POINTER}`);
+        return 1;
+    }
+    const transcriptRoot = resolveTranscriptRoot();
+    const plistPath = resolvePlistPath(SCHEDULE_LABEL, deps.homeDir);
+    const wrapperPath = resolveScheduleWrapperPath(resolveDataDir(dataDirFlag));
+    const bootout = deps.launchctl(['bootout', gui(deps, SCHEDULE_LABEL)]);
+    if (bootout.status !== 0 && lstatSafe(plistPath) !== undefined) {
+        deps.launchctl(['unload', '-w', plistPath]);
+    }
+    const removed = [];
+    if (removeIfPresent(plistPath, transcriptRoot))
+        removed.push(plistPath);
+    if (removeIfPresent(wrapperPath, transcriptRoot))
+        removed.push(wrapperPath);
+    try {
+        rmdirSync(dirname(wrapperPath));
+    }
+    catch {
+    }
+    if (removed.length === 0) {
+        console.log('recurring archive job: not installed — nothing to remove');
+    }
+    else {
+        console.log(['recurring archive job off — removed:', ...removed.map((path) => `  ${path}`)].join('\n') +
+            '\n  cron.log and the archive itself are untouched');
+    }
+    return 0;
+}
+export async function schedule(args = [], deps = realDeps()) {
+    const action = parseScheduleAction(args);
+    const dataDir = parseStringFlag(args, 'dataDir');
+    switch (action) {
+        case 'install':
+            return install(dataDir, deps);
+        case 'status':
+            return status(dataDir, deps);
+        case 'disable':
+            return disable(dataDir, deps);
+        case undefined:
+            console.error(`agent-lens schedule: an action is required — ${ACTIONS}`);
+            return 1;
+        default:
+            console.error(`agent-lens schedule: unknown action ${action} — expected ${ACTIONS}`);
+            return 1;
+    }
+}

package/dist/src/cli/commands/start.js

@@ -0,0 +1,83 @@
+import { discover, resolveArchiveRoot, resolveTranscriptRoot, } from '../../archive/index.js';
+import { startServer } from '../../server/index.js';
+export function emptyArchiveNotice(dataDir, transcriptRoot) {
+    const archiveRoot = resolveArchiveRoot(dataDir);
+    const root = resolveTranscriptRoot(transcriptRoot);
+    const entries = discover(root, archiveRoot);
+    if (entries.some((entry) => entry.presence !== 'source-only'))
+        return undefined;
+    return (`agent-lens: ${archiveRoot} is empty, so the session list will be too — ` +
+        `${entries.length} file(s) of transcripts under ${root} ` +
+        'are what `agent-lens archive` mirrors into it. Nothing is indexed until it runs.');
+}
+export function parsePort(args) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--port') {
+            const value = args[i + 1];
+            if (value === undefined) {
+                throw new Error('--port requires a value');
+            }
+            return parsePortValue(value);
+        }
+        if (arg.startsWith('--port=')) {
+            return parsePortValue(arg.slice('--port='.length));
+        }
+    }
+    return undefined;
+}
+function parsePortValue(value) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`invalid --port value: ${value}`);
+    }
+    return port;
+}
+export function parseHost(args) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--host') {
+            const value = args[i + 1];
+            if (value === undefined) {
+                throw new Error('--host requires a value');
+            }
+            return parseHostValue(value);
+        }
+        if (arg.startsWith('--host=')) {
+            return parseHostValue(arg.slice('--host='.length));
+        }
+    }
+    return undefined;
+}
+function parseHostValue(value) {
+    if (value === '') {
+        throw new Error('--host requires a value');
+    }
+    return value;
+}
+export async function start(args = []) {
+    const port = parsePort(args);
+    const host = parseHost(args);
+    const options = {};
+    if (port !== undefined)
+        options.port = port;
+    if (host !== undefined)
+        options.host = host;
+    const notice = emptyArchiveNotice();
+    if (notice !== undefined)
+        console.log(notice);
+    const handle = await startServer(options);
+    await new Promise((resolve) => {
+        let closing = false;
+        const shutdown = () => {
+            if (closing)
+                return;
+            closing = true;
+            void handle.close().then(resolve);
+        };
+        for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+            process.once(signal, shutdown);
+        }
+        console.log(`agent-lens listening on http://${host ?? '127.0.0.1'}:${handle.port}`);
+    });
+}