sealkeep 0.5.0

package/dist/src/adapters.js

@@ -0,0 +1,533 @@
+import { access, mkdir, open, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join, resolve, sep } from "node:path";
+import { fail } from "./errors.js";
+/**
+ * One table, so detection, hook installation and the setup API answer from the
+ * same facts. A second list of roots is how "where does Cursor live" starts
+ * drifting between the page that shows it and the installer that writes there.
+ */
+const AGENTS = {
+    codex: {
+        label: "Codex CLI",
+        root: (home) => join(home, ".codex"),
+        // Codex configures itself in TOML, so its hooks cannot be merged in by this
+        // build; `installAgentHooks` produces a reviewable fragment instead.
+        hookFile: (home) => join(home, ".codex", "config.toml"),
+        hookFileFormat: "toml",
+        archivable: true,
+        transcriptRoots: (home) => [join(home, ".codex", "sessions"), join(home, ".codex", "archived_sessions")]
+    },
+    claude: {
+        label: "Claude Code",
+        root: (home) => join(home, ".claude"),
+        hookFile: (home) => join(home, ".claude", "settings.json"),
+        hookFileFormat: "json",
+        archivable: true,
+        transcriptRoots: (home) => [join(home, ".claude", "projects")]
+    },
+    cursor: {
+        label: "Cursor",
+        root: (home) => join(home, ".cursor"),
+        hookFile: (home) => join(home, ".cursor", "hooks.json"),
+        hookFileFormat: "json",
+        archivable: false,
+        transcriptRoots: () => []
+    },
+    gemini: {
+        label: "Gemini CLI",
+        root: (home) => join(home, ".gemini"),
+        hookFile: (home) => join(home, ".gemini", "settings.json"),
+        hookFileFormat: "json",
+        archivable: false,
+        transcriptRoots: () => []
+    },
+    windsurf: {
+        label: "Windsurf",
+        root: (home) => join(home, ".codeium", "windsurf"),
+        hookFile: (home) => join(home, ".codeium", "windsurf", "hooks.json"),
+        hookFileFormat: "json",
+        archivable: false,
+        transcriptRoots: () => []
+    },
+    antigravity: {
+        label: "Antigravity",
+        root: (home) => join(home, ".gemini", "antigravity"),
+        hookFile: (home) => join(home, ".gemini", "antigravity", "hooks.json"),
+        hookFileFormat: "json",
+        archivable: false,
+        transcriptRoots: () => []
+    }
+};
+/** Every id `detectSetupAgents` reports on, in the order a setup page should show them. */
+export const SETUP_AGENT_IDS = Object.keys(AGENTS);
+/** The subset with a session adapter. Mirrors `AgentId` at runtime for schema use. */
+export const ARCHIVING_AGENT_IDS = ["codex", "claude"];
+/** Narrows a setup id to an archiving one, so callers prove the subset rather than casting to it. */
+export function isArchivingAgent(agent) {
+    return ARCHIVING_AGENT_IDS.includes(agent);
+}
+async function directoryExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Detect only well-known local roots; it never reads transcript contents. */
+export async function detectAgents(home = process.env.HOME ?? ".") {
+    return Promise.all(ARCHIVING_AGENT_IDS.map(async (agent) => {
+        const definition = AGENTS[agent];
+        const root = definition.root(home);
+        return { agent, root, transcriptRoots: definition.transcriptRoots(home), detected: await directoryExists(root) };
+    }));
+}
+/**
+ * Claude Code names each transcript directory after the session's cwd with the
+ * separators flattened to dashes ("/Users/x/repo" → "-Users-x-repo"). The
+ * decode is lossy by construction — a dash that was part of a directory name
+ * is indistinguishable from one that was a separator — so `project` is the
+ * final segment, which is the part a person recognises, and `projectPath` is
+ * the naive re-expansion, kept because "which /Users/… did this come from" is
+ * still worth answering approximately.
+ */
+export function claudeProjectFromPath(path) {
+    const marker = `${sep}.claude${sep}projects${sep}`;
+    const start = path.indexOf(marker);
+    if (start === -1)
+        return { project: null, projectPath: null };
+    const rest = path.slice(start + marker.length).split(sep);
+    // A .jsonl directly under projects/ is a stray file, not a project directory.
+    if (rest.length < 2)
+        return { project: null, projectPath: null };
+    const segments = rest[0].split("-").filter(Boolean);
+    if (segments.length === 0)
+        return { project: null, projectPath: null };
+    return { project: segments[segments.length - 1], projectPath: rest[0].replace(/-/g, "/") };
+}
+/**
+ * A rollout's first line is its session-meta record, and `cwd` in it is the
+ * only place Codex writes where the session ran. 8KB is the bound because this
+ * runs over every session on the machine from `listSessions`: a first line
+ * that keeps going past that is no longer metadata, and refusing to read
+ * further is what keeps "list 700 sessions" from becoming "read 700
+ * transcripts". Cached per (path, mtime) because a first line never changes
+ * once written; the mtime check only exists so a replaced file is re-read.
+ */
+const FIRST_LINE_BYTES = 8192;
+const codexIdentityCache = new Map();
+export async function codexProjectFromRollout(path, modifiedAt) {
+    const cached = codexIdentityCache.get(path);
+    if (cached && cached.modifiedAt === modifiedAt)
+        return { project: cached.project, projectPath: cached.projectPath };
+    const identity = await codexIdentityFromFirstLine(path);
+    codexIdentityCache.set(path, { modifiedAt, ...identity });
+    return identity;
+}
+/** `cwd` (or the older `cd`) on the record itself, or one level down in `payload`, where session-meta keeps it. */
+function recordedCwd(record, depth = 0) {
+    if (!record || typeof record !== "object" || Array.isArray(record))
+        return null;
+    const fields = record;
+    for (const key of ["cwd", "cd"]) {
+        const value = fields[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return depth === 0 ? recordedCwd(fields.payload, 1) : null;
+}
+/**
+ * `cwd` out of a first line too large to parse whole. Real session-meta lines
+ * run past 22KB because Codex embeds the full instructions text in the same
+ * record, so the 8KB read is a truncation and JSON.parse refuses it — which
+ * silently cost every real Codex session its project until a live rollout was
+ * tested. The key itself sits in the first few hundred bytes, before the
+ * instructions blob, so a bounded scan of the truncated head recovers it.
+ * First match wins; JSON string escapes in the value are decoded properly.
+ */
+function scannedCwd(text) {
+    const match = /"(?:cwd|cd)"\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(text);
+    if (!match)
+        return null;
+    try {
+        const value = JSON.parse(`"${match[1]}"`);
+        return typeof value === "string" && value.trim() ? value.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function codexIdentityFromFirstLine(path) {
+    const none = { project: null, projectPath: null };
+    let handle;
+    try {
+        handle = await open(path, "r");
+        const buffer = Buffer.alloc(FIRST_LINE_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, FIRST_LINE_BYTES, 0);
+        const text = buffer.subarray(0, bytesRead).toString("utf8");
+        const newline = text.indexOf("\n");
+        let cwd = null;
+        try {
+            cwd = recordedCwd(JSON.parse(newline === -1 ? text : text.slice(0, newline)));
+        }
+        catch {
+            // The line outgrew the read — the shape every real rollout has. The
+            // bounded scan reads the head that was fetched and nothing more.
+            cwd = scannedCwd(text);
+        }
+        if (!cwd)
+            return none;
+        const segments = cwd.split(/[\\/]/).filter(Boolean);
+        return segments.length === 0 ? none : { project: segments[segments.length - 1], projectPath: cwd };
+    }
+    catch {
+        // An unreadable first line is a session without a project, not an error:
+        // the list must survive whatever a vendor format update does.
+        return none;
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+/**
+ * Fills project identity in place, after the limit cut — resolving only what
+ * will be returned keeps the codex reads proportional to the page, not the
+ * disk. Claude's identity is pure path arithmetic; codex needs the bounded
+ * first-line read, capped at 16 in flight so hundreds of cold files neither
+ * run serially nor open hundreds of descriptors at once.
+ */
+async function attachProjects(candidates) {
+    const rollouts = [];
+    for (const candidate of candidates) {
+        if (candidate.agent === "claude")
+            Object.assign(candidate, claudeProjectFromPath(candidate.path));
+        else
+            rollouts.push(candidate);
+    }
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(16, rollouts.length) }, async () => {
+        while (next < rollouts.length) {
+            const candidate = rollouts[next++];
+            Object.assign(candidate, await codexProjectFromRollout(candidate.path, candidate.modifiedAt));
+        }
+    }));
+}
+/**
+ * Collects every transcript under `root`.
+ *
+ * Deliberately unbounded: truncating here would truncate in readdir order,
+ * which has nothing to do with time, so "the most recent N" would be N
+ * arbitrary sessions that happened to be walked first. Only metadata is read,
+ * so the cost is one stat per file.
+ */
+async function walkJsonl(root, agent, output) {
+    if (!(await directoryExists(root)))
+        return;
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            await walkJsonl(path, agent, output);
+        else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+            const file = await stat(path);
+            output.push({ agent, path, bytes: file.size, modifiedAt: file.mtime.toISOString() });
+        }
+    }
+}
+/**
+ * Lists metadata for recent transcripts, never their conversations. The one
+ * read into a file is the codex rollout's first line, which is the session's
+ * own metadata record — what was said in the session stays unread.
+ */
+export async function findTranscripts(agent, home = process.env.HOME ?? ".", limit = 50) {
+    const install = (await detectAgents(home)).find((item) => item.agent === agent);
+    const files = [];
+    for (const root of install.transcriptRoots)
+        await walkJsonl(root, agent, files);
+    const recent = files.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt)).slice(0, limit);
+    await attachProjects(recent);
+    return recent;
+}
+/**
+ * The one command a Sealkeep hook ever runs, built in one place.
+ *
+ * Detection matches installed hooks on the `hook enqueue --agent <id>` part of
+ * it, so the command and the thing that recognises it can never disagree about
+ * what a Sealkeep hook looks like.
+ */
+export function hookCommand(agent, executable = "vaultline", dataDir = "~/.vaultline") {
+    return `${executable} ${hookMarker(agent)} --data-dir ${dataDir}`;
+}
+/** The substring that identifies a Sealkeep hook for one agent, wherever it is written. */
+export function hookMarker(agent) {
+    return `hook enqueue --agent ${agent}`;
+}
+/**
+ * Returns a reviewable config fragment. It is intentionally not installed into
+ * an agent's settings: users must review and merge it themselves. The hook only
+ * enqueues local work, so it needs no recovery phrase and no network access.
+ */
+export function hookConfig(agent, executable = "vaultline", dataDir = "~/.vaultline") {
+    const command = hookCommand(agent, executable, dataDir);
+    const entry = (timeout) => [{ hooks: [{ type: "command", command, timeout }] }];
+    // The resume side of the pair: SessionStart checks whether the transcript
+    // the agent is about to read left this disk for the vault, and puts it back
+    // first — resume never learns the file was away. Generous timeout, because
+    // an offloaded multi-GB session fetches from the bucket; the command itself
+    // never exits nonzero, so a slow restore is the worst case, not a broken one.
+    const rehydrate = `${executable} hook rehydrate --agent ${agent} --data-dir ${dataDir}`;
+    const rehydrateEntry = [{ matcher: "resume", hooks: [{ type: "command", command: rehydrate, timeout: 300 }] }];
+    if (agent === "codex")
+        return {
+            description: "Sealkeep records an archive intent locally, and puts archived transcripts back before a resume reads them. It holds no secret; rehydration uses this machine's keystore.",
+            hooks: {
+                SessionEnd: [{ hooks: [{ type: "command", command, timeout: 3, statusMessage: "Queuing encrypted archive" }] }],
+                PostCompact: entry(3),
+                SessionStart: rehydrateEntry
+            },
+            _vaultlineNote: "Run `sealkeep queue run` (with VAULTLINE_RECOVERY_PHRASE set) to encrypt queued sessions. If this Codex version has no SessionStart hook, the entry is ignored; `sealkeep recover <session-file>` is the manual door."
+        };
+    return {
+        hooks: { SessionEnd: entry(5), SessionStart: rehydrateEntry },
+        _vaultlineNote: "Merge the hooks object into ~/.claude/settings.json. The hook stores no secret; run `sealkeep queue run` with VAULTLINE_RECOVERY_PHRASE to encrypt queued sessions. SessionStart(resume) puts archived transcripts back before the resume reads them."
+    };
+}
+/**
+ * Whether Sealkeep could put its hook in this file.
+ *
+ * A missing file is not a refusal — most agents create theirs on first use —
+ * so the question becomes whether its directory will accept a new file. Any
+ * other error is answered "no": claiming an agent is hookable and then failing
+ * to write is the outcome this whole endpoint exists to avoid.
+ */
+async function hookFileWritable(path) {
+    try {
+        await access(path, constants.W_OK);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            return false;
+        try {
+            await access(dirname(path), constants.W_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Reads an agent's hook file as text, whatever its format.
+ *
+ * Detection only has to answer "is our command in here", and the command is a
+ * literal string in JSON and TOML alike, so this needs no parser and cannot be
+ * defeated by a config shape this build has not seen.
+ */
+async function hookFileText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function statusFor(detection) {
+    if (!detection.detected)
+        return { status: "not-installed", note: `No ${detection.root} on this machine.` };
+    if (detection.hooksInstalled)
+        return { status: "hooked", note: null };
+    if (!detection.hookFileWritable)
+        return { status: "found-but-unwritable", note: `${detection.hookFile} cannot be written or created, so Sealkeep cannot hook ${detection.label} here.` };
+    if (!detection.archivable) {
+        return {
+            status: "found-but-unsupported",
+            // A reason, not a sentence. Callers introduce the agent themselves — the
+            // wizard row already opens with "Sealkeep can see Cursor here but
+            // cannot archive its sessions yet" — so repeating that here produced the
+            // same statement twice in one paragraph, followed by a stray full stop.
+            note: `\`sealkeep hook enqueue\` accepts only codex and claude, and this agent's hook payload carries no transcript path, so a hook here would fail on every session`
+        };
+    }
+    if (detection.hookFileFormat !== "json") {
+        return { status: "manual-merge-required", note: `${detection.hookFile} is TOML and this build has no TOML writer, so Sealkeep writes a reviewable fragment instead of editing it.` };
+    }
+    return { status: "ready", note: null };
+}
+/**
+ * Everything first-run setup needs about the agents on this machine.
+ *
+ * Unlike `detectAgents`, which answers the archiving question and so lists only
+ * the agents with a session adapter, this answers the setup question: what is
+ * here, where its hooks live, whether ours are already among them, and whether
+ * we could write there at all. It reads no transcript and no config value —
+ * only whether one string appears in a config file.
+ */
+/** Total size and count of one agent's transcripts. Reads sizes, never contents. */
+async function measureSessions(roots) {
+    const found = [];
+    for (const root of roots)
+        await walkJsonl(root, "codex", found);
+    return { sessionBytes: found.reduce((total, item) => total + item.bytes, 0), sessionCount: found.length };
+}
+export async function detectSetupAgents(home = process.env.HOME ?? ".") {
+    return Promise.all(SETUP_AGENT_IDS.map(async (agent) => {
+        const definition = AGENTS[agent];
+        const root = definition.root(home);
+        const hookFile = definition.hookFile(home);
+        const [detected, contents, writable] = await Promise.all([directoryExists(root), hookFileText(hookFile), hookFileWritable(hookFile)]);
+        // What this agent is costing in disk right now. It is the reason anyone
+        // installs Sealkeep, and until it is on screen the problem is invisible —
+        // sessions accumulate in a directory nobody opens. Metadata only, one stat
+        // per file, and skipped entirely for an agent with no adapter, where the
+        // number would be a figure we cannot act on.
+        const sessions = detected && definition.archivable
+            ? await measureSessions(definition.transcriptRoots(home))
+            : { sessionBytes: 0, sessionCount: 0 };
+        const base = {
+            agent, label: definition.label, detected, root, hookFile,
+            hookFileFormat: definition.hookFileFormat,
+            hookFileExists: contents !== null,
+            hookFileWritable: writable,
+            hooksInstalled: contents !== null && contents.includes(hookMarker(agent)),
+            archivable: definition.archivable,
+            ...sessions
+        };
+        return { ...base, ...statusFor(base) };
+    }));
+}
+/** Written beside the original before Sealkeep edits another program's config, so a bad merge is always undoable. */
+async function backupHookFile(path, contents) {
+    const backup = `${path}.vaultline-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    await writeFile(backup, contents, { mode: 0o600 });
+    return backup;
+}
+/**
+ * Merges Sealkeep's hook entries into whatever the agent already declares.
+ *
+ * Every key the agent owns is carried through untouched and our entry is
+ * appended rather than substituted, because this file belongs to another
+ * program: a person's own hooks surviving a Sealkeep install matters more
+ * than a tidy document.
+ */
+function mergeHooks(existing, ours) {
+    const base = existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+    for (const [event, entries] of Object.entries(ours)) {
+        // One agent's config declares events another does not; an absent event is
+        // nothing to merge rather than an empty list to write.
+        if (!entries)
+            continue;
+        const current = Array.isArray(base[event]) ? [...base[event]] : [];
+        base[event] = [...current, ...entries];
+    }
+    return base;
+}
+/** Atomic, owner-only, and never a partial file: a half-written settings.json breaks the agent it belongs to. */
+async function writeJsonAtomic(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const temp = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+    await rename(temp, path);
+}
+/**
+ * Installs Sealkeep's hook into the agents it can, and says why for the rest.
+ *
+ * Idempotent by construction: a second call finds its own marker and writes
+ * nothing. Nothing here reports `installed: true` unless the agent's own config
+ * now contains the command — a fragment written for manual review is reported
+ * as what it is.
+ */
+export async function installAgentHooks(agents, options) {
+    const home = options.home ?? process.env.HOME ?? ".";
+    const executable = options.executable ?? "vaultline";
+    const detections = new Map((await detectSetupAgents(home)).map((detection) => [detection.agent, detection]));
+    const outcomes = [];
+    for (const agent of agents) {
+        const detection = detections.get(agent);
+        const base = { agent, hookFile: detection.hookFile, installed: false, alreadyInstalled: false, backupPath: null, fragmentPath: null, reason: null };
+        if (detection.status === "hooked") {
+            outcomes.push({ ...base, installed: true, alreadyInstalled: true });
+            continue;
+        }
+        if (detection.status === "not-installed" || detection.status === "found-but-unwritable" || detection.status === "found-but-unsupported") {
+            outcomes.push({ ...base, reason: detection.note });
+            continue;
+        }
+        // Only an agent with a session adapter can still be here: `statusFor` sent
+        // every other id to "found-but-unsupported" above. The guard is what makes that
+        // provable rather than merely true.
+        if (!isArchivingAgent(agent)) {
+            outcomes.push({ ...base, reason: detection.note });
+            continue;
+        }
+        if (detection.status === "manual-merge-required") {
+            // The fragment is a Sealkeep-owned artifact, exactly as `sealkeep setup`
+            // has always written it. It is not an install and is not reported as one.
+            const fragmentPath = join(options.dataDir, "integrations", `${agent}-hooks.json`);
+            await writeJsonAtomic(fragmentPath, hookConfig(agent, executable, options.dataDir));
+            outcomes.push({ ...base, fragmentPath, reason: detection.note });
+            continue;
+        }
+        const raw = detection.hookFileExists ? await hookFileText(detection.hookFile) : "";
+        let parsed = {};
+        if (raw && raw.trim()) {
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                // Refusing beats guessing: rewriting a file we could not read would
+                // discard settings that belong to somebody else.
+                outcomes.push({ ...base, reason: `${detection.hookFile} is not valid JSON, so Sealkeep will not rewrite it. Fix or move it and try again.` });
+                continue;
+            }
+        }
+        const document = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? { ...parsed } : {};
+        document.hooks = mergeHooks(document.hooks, hookConfig(agent, executable, options.dataDir).hooks);
+        const backupPath = raw && raw.trim() ? await backupHookFile(detection.hookFile, raw) : null;
+        await writeJsonAtomic(detection.hookFile, document);
+        outcomes.push({ ...base, installed: true, backupPath });
+    }
+    return outcomes;
+}
+const PATH_KEYS = ["transcript_path", "transcriptPath", "rollout_path", "rolloutPath"];
+const EVENT_KEYS = ["hook_event_name", "hookEventName", "event", "type"];
+const SESSION_KEYS = ["session_id", "sessionId", "conversation_id"];
+function firstString(payload, keys) {
+    for (const key of keys) {
+        const value = payload[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+/**
+ * Accepts Codex `SessionEnd`/`PostCompact` and Claude `SessionEnd` payloads. Unknown
+ * vendor fields are ignored rather than parsed, so a schema change cannot break preservation.
+ */
+export async function hookEventFromStdin(agent, stdin) {
+    let payload;
+    try {
+        payload = JSON.parse(stdin);
+    }
+    catch {
+        return fail("hook_payload_invalid", "Hook payload must be a JSON object on stdin");
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return fail("hook_payload_invalid", "Hook payload must be a JSON object on stdin");
+    const record = payload;
+    const raw = firstString(record, PATH_KEYS);
+    if (!raw)
+        return fail("hook_payload_invalid", `Hook payload has no transcript path (looked for ${PATH_KEYS.join(", ")})`);
+    const path = resolve(raw);
+    try {
+        await access(path, constants.R_OK);
+    }
+    catch {
+        return fail("source_unreadable", `Transcript is not readable: ${path}`, { sourcePath: path });
+    }
+    return { agent, event: firstString(record, EVENT_KEYS) ?? "unknown", sourcePath: path, sessionId: firstString(record, SESSION_KEYS) };
+}
+export async function transcriptPathFromHook(stdin, agent = "codex") {
+    return (await hookEventFromStdin(agent, stdin)).sourcePath;
+}

package/dist/src/audit.d.ts

@@ -0,0 +1,24 @@
+export type AuditAction = "archive.create" | "archive.restore" | "archive.migrate" | "archive.rewrap" | "archive.prune" | "archive.offload" | "archive.delete" | "phrase.rotate" | "password.change" | "archive.share" | "source.reclaim" | "recipient.add" | "recipient.remove" | "upload.verify" | "remote.check" | "retention.approve";
+export type LocalAuditEvent = {
+    id: string;
+    at: string;
+    action: AuditAction;
+    outcome: "allowed" | "denied";
+    /** Identifiers, counts, and paths only. Never transcript content or secrets. */
+    detail?: Record<string, string | number | boolean | null>;
+};
+export declare const auditPath: (dataDir: string) => string;
+/**
+ * Append-only local audit log.
+ *
+ * It exists so a user can answer "what did Sealkeep do to my files?" without
+ * trusting a server. Entries are one JSON object per line, rotated at 5 MB, and
+ * carry identifiers and counts only — never plaintext, phrases, or key material.
+ */
+export declare function recordAudit(dataDir: string, action: AuditAction, outcome: "allowed" | "denied", detail?: LocalAuditEvent["detail"]): Promise<LocalAuditEvent>;
+export declare function readAudit(dataDir: string, options?: {
+    limit?: number;
+    action?: AuditAction;
+}): Promise<LocalAuditEvent[]>;
+/** CSV export for teams that keep audit evidence outside the machine. */
+export declare function toCsv(events: readonly LocalAuditEvent[]): string;

package/dist/src/audit.js

@@ -0,0 +1,41 @@
+import { appendFile, mkdir, readFile, rename, stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+const MAX_BYTES = 5 * 1024 * 1024;
+export const auditPath = (dataDir) => join(dataDir, "audit.jsonl");
+/**
+ * Append-only local audit log.
+ *
+ * It exists so a user can answer "what did Sealkeep do to my files?" without
+ * trusting a server. Entries are one JSON object per line, rotated at 5 MB, and
+ * carry identifiers and counts only — never plaintext, phrases, or key material.
+ */
+export async function recordAudit(dataDir, action, outcome, detail) {
+    const event = { id: randomUUID(), at: new Date().toISOString(), action, outcome, detail };
+    const path = auditPath(dataDir);
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    const size = await stat(path).then((info) => info.size).catch(() => 0);
+    if (size > MAX_BYTES)
+        await rename(path, `${path}.1`).catch(() => undefined);
+    await appendFile(path, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+    return event;
+}
+export async function readAudit(dataDir, options = {}) {
+    const raw = await readFile(auditPath(dataDir), "utf8").catch(() => "");
+    const events = raw.split("\n").filter(Boolean).flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+    const filtered = options.action ? events.filter((event) => event.action === options.action) : events;
+    return filtered.slice(-(options.limit ?? 200));
+}
+/** CSV export for teams that keep audit evidence outside the machine. */
+export function toCsv(events) {
+    const escape = (value) => `"${String(value ?? "").replace(/"/g, '""')}"`;
+    const header = "id,at,action,outcome,detail";
+    return [header, ...events.map((event) => [event.id, event.at, event.action, event.outcome, JSON.stringify(event.detail ?? {})].map(escape).join(","))].join("\n");
+}

package/dist/src/autopilot.d.ts

@@ -0,0 +1,77 @@
+import { ArchiveQueue } from "./queue.js";
+import { type RetentionSettings } from "./retention.js";
+import { type BackendName } from "./secrets.js";
+import { serviceStatus, type ServiceOptions, type ServiceOutcome } from "./service.js";
+import { type Liveness } from "./heartbeat.js";
+export type AutopilotOptions = {
+    phrase?: string;
+    /** Keep the phrase in this machine's keystore so the service can run unattended. */
+    remember?: boolean;
+    /** Let the service reclaim disk once a remote copy is verified. */
+    reclaim?: boolean;
+    olderThanDays?: number;
+    graceDays?: number;
+    home?: string;
+    platform?: NodeJS.Platform;
+    exec?: ServiceOptions["exec"];
+    cliPath?: string;
+    /** Pin the keystore. Omitted, the strongest backend this machine offers is used. */
+    backend?: BackendName;
+    /** Show what would happen and change nothing. */
+    dryRun?: boolean;
+};
+export type AutopilotResult = {
+    vaultId: string;
+    /** Present only on first setup. Shown once, then never retrievable. */
+    recoveryPhrase?: string;
+    remembered: {
+        backend: string;
+    } | null;
+    retention: RetentionSettings;
+    service: ServiceOutcome;
+    agents: string[];
+    found: {
+        sessions: number;
+        bytes: number;
+    };
+    queued: number;
+    reclaimEnabled: boolean;
+    hasRemoteTarget: boolean;
+    notes: string[];
+};
+/**
+ * Turns Sealkeep into something that runs itself.
+ *
+ * One call sets up the vault, teaches this machine to unlock it, picks a retention
+ * policy, sweeps up the sessions already on disk, and installs a login service. The
+ * safety gates are unchanged: reclamation still requires a verified remote copy, an
+ * idle file, and an elapsed grace period, so enabling it here cannot delete anything
+ * until a bucket is configured and an upload has been checked.
+ */
+export declare function enableAutopilot(dataDir: string, options?: AutopilotOptions): Promise<AutopilotResult>;
+export type AutopilotStatus = {
+    running: boolean;
+    /** What the service is actually doing, read from its own heartbeat. */
+    live: Liveness;
+    service: Awaited<ReturnType<typeof serviceStatus>>;
+    phraseAvailable: boolean;
+    retention: RetentionSettings;
+    hasRemoteTarget: boolean;
+    queue: Awaited<ReturnType<ArchiveQueue["stats"]>>;
+};
+export declare function autopilotStatus(dataDir: string, options?: AutopilotOptions): Promise<AutopilotStatus>;
+/**
+ * Stops the service and forgets the stored phrase. Archives are untouched: turning
+ * automation off is not a way to lose data.
+ */
+export declare function disableAutopilot(dataDir: string, options?: AutopilotOptions): Promise<{
+    service: ServiceOutcome;
+    forgotPhrase: boolean;
+    retention: {
+        policy: "local-only" | "sync-only" | "archive-and-reclaim" | "manual-approval";
+        olderThanDays: number;
+        graceDays: number;
+        deleteAfterDays?: number | null;
+    };
+    archivesKept: boolean;
+}>;