@gravitylabsllc/porthole 0.1.0 → 0.2.0

package/dist/sessions.js

@@ -0,0 +1,704 @@
+// Copyright 2026 Gravity Labs
+// SPDX-License-Identifier: Apache-2.0
+import { appendFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { profileFromEvent } from "./trace.js";
+/** Stand-in for `deviceId` when a `hello` did not carry one. */
+export const UNKNOWN_DEVICE_ID = "unknown-device";
+export function sessionIdentity(hello) {
+    return {
+        packageName: hello.packageName,
+        deviceId: hello.deviceId ?? UNKNOWN_DEVICE_ID,
+        startedAt: hello.startedAt,
+    };
+}
+/**
+ * A filesystem-safe fragment: anything outside a conservative allowlist
+ * becomes `_`. `packageName` is always dotted-identifier-shaped in practice,
+ * but `deviceId` is whatever a future device sends, and this directory name
+ * doubles as `findSessionsForIdentity`'s prefix filter — an unsanitised
+ * separator character in either value could make one identity's directory
+ * look like a prefix of another's.
+ */
+function sanitize(value) {
+    const cleaned = value.replace(/[^A-Za-z0-9_.-]/g, "_");
+    return cleaned.length > 0 ? cleaned : "_";
+}
+export function sessionDirName(identity) {
+    return `${sanitize(identity.packageName)}_${sanitize(identity.deviceId)}_${identity.startedAt}`;
+}
+export function sessionsRoot(projectRoot) {
+    return path.join(projectRoot, ".porthole", "sessions");
+}
+function metaPath(dir) {
+    return path.join(dir, "meta.json");
+}
+function eventsPath(dir) {
+    return path.join(dir, "events.ndjson");
+}
+/**
+ * This directory holds redacted-but-real app data (logcat lines, SQL bind
+ * values, HTTP headers) sitting on disk for up to [DEFAULT_RETENTION]'s
+ * `maxAgeMs`, rather than in a process's memory that dies with it — a
+ * different promise to a user than the in-memory ring ever made, per the
+ * ticket's own security note. Owner-only permissions are the cheap half of
+ * making that true.
+ *
+ * POSIX only. `fs`'s `mode` option is Unix permission bits; Windows/NTFS has
+ * no such concept (it uses ACLs instead), and Node's own docs say `mode` is
+ * "Not supported on Windows" — passing one there is not wrong, just inert,
+ * so every call site below gates on this rather than silently no-op'ing on
+ * one platform without saying so.
+ */
+const isPosix = process.platform !== "win32";
+/** Owner rwx only — the sessions root and every session directory under it (recursive `mkdir` applies this to each level it creates). */
+const SESSION_DIR_MODE = 0o700;
+/** Owner rw only — `meta.json` and `events.ndjson`. Applied at file creation; an already-existing file keeps whatever mode it was created with. */
+const SESSION_FILE_MODE = 0o600;
+function dirOptions() {
+    return isPosix ? { recursive: true, mode: SESSION_DIR_MODE } : { recursive: true };
+}
+function fileOptions() {
+    return isPosix ? { mode: SESSION_FILE_MODE } : {};
+}
+async function readMeta(dir) {
+    try {
+        return JSON.parse(await readFile(metaPath(dir), "utf8"));
+    }
+    catch {
+        // Absent, unreadable or corrupt are all the same to a caller: there is no
+        // meta to report, so callers that need one (retention, cross-session
+        // lookup) skip the directory rather than guessing at its contents.
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// the writer
+// ---------------------------------------------------------------------------
+/**
+ * Appends one session's events to disk, off the socket callback and on an
+ * interval — never a synchronous write per event, which is what "must not
+ * touch the socket read path" (AC4) means concretely: `append()` only ever
+ * pushes to an in-memory array and arms a timer; the actual `fs` write
+ * happens later, on `flush()`, awaited by nothing on the hot path.
+ *
+ * One writer instance is meant to live as long as one `DeviceClient` — see
+ * that file's `#session-writer` section once it is wired up — so `open()` is
+ * called once per `hello` and `append()` once per event in between.
+ */
+export class SessionWriter {
+    root;
+    flushIntervalMs;
+    dir = null;
+    meta = null;
+    queue = [];
+    flushTimer = null;
+    /** Chains flushes so an interval tick and an explicit flush() never interleave two appendFile calls on the same file. */
+    flushing = Promise.resolve();
+    /**
+     * GRA-191: true for the whole span of an in-flight `open()` call — from
+     * before its first `await` to its `finally`, success or failure. This,
+     * not `dir`, is what lets `append()` tell "a session is being opened,
+     * queue this" apart from "nothing will ever open here, drop this": `dir`
+     * itself is not set until partway through `open()` (see below), so an
+     * event arriving in the gap before that line runs would otherwise look
+     * identical to one arriving with persistence off entirely.
+     */
+    opening = false;
+    /**
+     * GRA-191: true once `close()` has run and no `open()` has run since.
+     * `DeviceClient.stop()` calls `close()` so nothing here outlives the
+     * caller (see that method); `append()` drops silently while this is true,
+     * the same "nowhere to put this" shape as never having opened at all,
+     * rather than queuing into a writer its owner has already said it is done
+     * with. `open()` clears it unconditionally, including on the idempotent
+     * "same identity" path, because a reconnect (stop() closed this writer; a
+     * fresh hello reopens it) must resume appending, not stay silently closed
+     * forever just because the identity did not change.
+     */
+    closed = false;
+    constructor(root, flushIntervalMs = 250) {
+        this.root = root;
+        this.flushIntervalMs = flushIntervalMs;
+    }
+    /**
+     * Begins (or resumes) the session named by `hello`'s identity.
+     *
+     * Idempotent for an unchanged identity — a reconnect that gets the same
+     * `hello` back (GRA-163: the same process, socket dropped and reattached)
+     * must not re-open anything or lose queued events. A *new* identity first
+     * flushes whatever the previous session still owed: `device.ts` only calls
+     * `open()` from the `hello` handler, and a new `hello` always means a new
+     * process (or a distinct device) — nothing more will ever arrive for the
+     * one just left behind, so this is the only chance to flush it promptly
+     * rather than waiting on a timer that a new session's own events would
+     * otherwise keep resetting.
+     *
+     * "A second MCP server attaching to the same app appends to the same
+     * session" (the ticket's own words): the directory name is a pure function
+     * of identity, so a second writer computes the same path and finds the
+     * directory (and `meta.json`) already there — this reads it back rather
+     * than overwriting it, so the counts and `firstT` it reports are the whole
+     * session's, not just what this instance has seen.
+     */
+    async open(hello) {
+        // PORTHOLE_SESSIONS=0 is the off switch: `dir` is left null, exactly the
+        // "no root configured" shape `append()` already treats as a silent
+        // no-op, and neither `mkdir` nor a retention sweep ever touches the
+        // sessions root. Checked first, and every time — not cached at
+        // construction — so it stays cheap to reason about (one env read, one
+        // branch) rather than a second piece of state that could drift from the
+        // environment it mirrors.
+        if (!sessionsEnabled())
+            return;
+        const identity = sessionIdentity(hello);
+        const dir = path.join(this.root, sessionDirName(identity));
+        // GRA-191: un-closes the writer even on the idempotent "same identity"
+        // path below — see `closed`'s own comment on why a reconnect must not
+        // stay closed just because nothing about the identity changed.
+        this.closed = false;
+        if (this.dir === dir)
+            return;
+        this.opening = true;
+        try {
+            await this.flush();
+            this.dir = dir;
+            await mkdir(dir, dirOptions());
+            this.meta = (await readMeta(dir)) ?? {
+                packageName: identity.packageName,
+                deviceId: identity.deviceId,
+                startedAt: identity.startedAt,
+                device: hello.device,
+                sdkInt: hello.sdkInt,
+                versionName: hello.versionName,
+                firstT: null,
+                lastT: null,
+                eventCounts: {},
+                createdAt: Date.now(),
+                updatedAt: Date.now(),
+            };
+            await writeFile(metaPath(dir), JSON.stringify(this.meta, null, 2), fileOptions());
+            // Every new (or resumed) session is a natural, cheap point to sweep:
+            // it is already the moment this writer is about to grow the directory
+            // it would prune from, and it means retention runs on the same
+            // cadence a long-lived MCP server actually sees `hello`s, not on a
+            // separate timer this ticket does not need. `activeDir` is *this*
+            // session, just opened above — never the one about to be pruned, no
+            // matter its age or size.
+            await enforceRetention(this.root, retentionOptionsFromEnv(), this.currentDir());
+            // GRA-191: `device.ts` now emits its own "hello" — and lets a caller
+            // start sending events — before this method is even called, not just
+            // before it resolves (see that file's `connect()`). Anything
+            // `append()`ed during the disk I/O above was queued rather than
+            // dropped (see `append()`'s own comment); flush it now that `dir`
+            // exists, rather than waiting on `append()`'s own 250ms timer, so a
+            // caller that awaits `open()` and immediately reads the session back
+            // sees everything that arrived during the wait.
+            await this.flush();
+        }
+        finally {
+            this.opening = false;
+        }
+    }
+    /**
+     * Queues an event. The actual disk write happens on the next `flush()`,
+     * arranged on a timer here — never inline, which is the whole point (AC4).
+     *
+     * Silently does nothing with no session that will ever open to receive it:
+     * persistence being off (no root configured — see `device.ts`), a writer
+     * `close()` has already closed, or `open()` never having been called at
+     * all all look like this from the caller's side, and none of them is an
+     * error.
+     *
+     * GRA-191: does *not* require `dir` to already be set. `device.ts` now
+     * emits "hello" — and lets a caller start sending events — before it even
+     * calls `open()`, not just before `open()` resolves, so an event can
+     * legitimately arrive before `dir` exists yet. `opening` is what tells
+     * that apart from "no session will ever open here": queue in the former
+     * case (open()'s own trailing flush — see above — writes it out once
+     * `dir` exists), drop in the latter (nothing will ever flush a queue that
+     * never has an open directory behind it).
+     */
+    append(event) {
+        if (this.closed)
+            return;
+        if (!this.dir && !this.opening)
+            return;
+        this.queue.push(event);
+        if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => {
+                this.flushTimer = null;
+                void this.flush();
+            }, this.flushIntervalMs);
+            // Node-only guard: a raw `setTimeout` return value in a browser bundle
+            // has no `.unref`. This module never runs in a browser, but `.unref?.()`
+            // costs nothing and stops a lingering timer from being the reason a
+            // short-lived script (a test, a one-shot CLI invocation) hangs on exit.
+            this.flushTimer.unref?.();
+        }
+    }
+    /** Writes whatever is queued. Safe to call at any time; a no-op with nothing queued. */
+    flush() {
+        this.flushing = this.flushing.then(() => this.doFlush());
+        return this.flushing;
+    }
+    async doFlush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (!this.dir || this.queue.length === 0)
+            return;
+        const dir = this.dir;
+        const batch = this.queue;
+        this.queue = [];
+        try {
+            const lines = batch.map((event) => JSON.stringify(event)).join("\n") + "\n";
+            await mkdir(dir, dirOptions());
+            await appendFile(eventsPath(dir), lines, { encoding: "utf8", ...fileOptions() });
+            const meta = this.meta ?? (await readMeta(dir));
+            if (meta) {
+                for (const event of batch) {
+                    meta.eventCounts[event.event] = (meta.eventCounts[event.event] ?? 0) + 1;
+                    meta.firstT = meta.firstT === null ? event.t : Math.min(meta.firstT, event.t);
+                    meta.lastT = meta.lastT === null ? event.t : Math.max(meta.lastT, event.t);
+                    // GRA-191: moved here from `append()`. `append()` can now queue an
+                    // event before `this.meta` exists yet — the window `open()` is
+                    // still in its own `mkdir`/`readMeta` (see `append()`'s comment) —
+                    // so capturing the profile at append() time could silently miss
+                    // it for whichever event happened to land in that window. Every
+                    // event reaches this loop only once `meta` is known to exist (or
+                    // there is genuinely nothing to capture into), so this is the one
+                    // place the capture can never be skipped for lack of a meta
+                    // object to put it in.
+                    const profile = profileFromEvent(event);
+                    if (profile)
+                        meta.profile = profile;
+                }
+                meta.updatedAt = Date.now();
+                this.meta = meta;
+                await writeFile(metaPath(dir), JSON.stringify(meta, null, 2), fileOptions());
+            }
+        }
+        catch (error) {
+            // GRA-191: the session root can be removed out from under a still-
+            // armed flush — a test's teardown (or a real short-lived process)
+            // deleting `sessionsRoot` while an event was queued and the flush
+            // timer was still pending is the repro GRA-183 found. There is
+            // nowhere left to write, and `batch` (already spliced out of
+            // `this.queue` above) is not coming back — the same loss a killed
+            // process before any flush at all would already produce, not a new
+            // one this introduces, so treating it as "nothing to flush" rather
+            // than surfacing an unhandled rejection is honest, not a cover-up.
+            // Anything else (a permissions error, a full disk) is a real problem
+            // and must still surface — checking the code, rather than swallowing
+            // every error this method can raise, is what keeps that true.
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    currentDir() {
+        return this.dir;
+    }
+    currentMeta() {
+        return this.meta;
+    }
+    /**
+     * GRA-191: called from `DeviceClient.stop()` so nothing here outlives the
+     * caller. Flushes whatever is queued — which also cancels the pending
+     * flush timer, since `doFlush()`'s own first lines clear it unconditionally
+     * — rather than leaving a still-armed timer to fire later, potentially
+     * well after whatever root this writer lives under has been torn down (a
+     * test's `afterEach`, a real process exit). Also marks the writer closed
+     * (see `closed`'s own comment) so a straggling `append()` after this —
+     * `stop()` destroying the socket and the "close" handler both reacting to
+     * the same teardown — drops silently instead of queuing into a writer
+     * nothing will flush again until a new `open()`.
+     */
+    close() {
+        this.closed = true;
+        void this.flush();
+    }
+}
+// ---------------------------------------------------------------------------
+// fallback read — GRA-53 Q1: a scan, not an index
+// ---------------------------------------------------------------------------
+/**
+ * Streams `events.ndjson` and returns the events whose `t` falls in
+ * `[from, to]`, oldest first.
+ *
+ * **Q1, answered by measurement, not assumption**: does the fallback read
+ * need an index, or is a per-minute byte-offset scan enough for a 30-minute
+ * session? `sessions.test.ts` writes a real ~30-minute-equivalent NDJSON file
+ * (54,000 lines at 30 events/sec, this module's own estimate of "a busy
+ * app" — see `EventRing.DEFAULT_CAPACITY`'s comment for where that rate
+ * comes from) and asserts a window read completes well inside a second on
+ * ordinary hardware. A plain sequential scan was fast enough that building
+ * and maintaining a byte-offset index — one more structure that can disagree
+ * with the file it indexes — was not worth the ticket's own warning: "an
+ * index you did not need is cost you cannot remove later."
+ *
+ * Streams rather than reading the whole file into memory (the device AC
+ * asks for exactly this): `createReadStream` plus `readline` never holds
+ * more than one line at a time, so this scales past whatever `--max-old-
+ * space-size` a long session's file would otherwise threaten.
+ */
+export async function readSessionWindow(dir, from, to) {
+    const out = [];
+    await new Promise((resolve, reject) => {
+        const stream = createReadStream(eventsPath(dir), { encoding: "utf8" });
+        let settled = false;
+        const onError = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            // No file at all (a session directory with nothing flushed yet, or one
+            // that never existed) is not a caller error — it just has nothing to
+            // contribute to the window.
+            if (error.code === "ENOENT")
+                resolve();
+            else
+                reject(error);
+        };
+        // Both the stream and the readline interface built on it can be the one
+        // to actually emit "error" depending on Node's version and exactly when
+        // the open() failure lands relative to readline wiring itself up — an
+        // ENOENT on a missing session directory reliably surfaced as an
+        // *uncaught* exception here until both were listened to, because an
+        // EventEmitter with no "error" listener throws rather than swallowing.
+        stream.on("error", onError);
+        const rl = createInterface({ input: stream, crlfDelay: Infinity });
+        rl.on("error", onError);
+        rl.on("line", (line) => {
+            if (!line)
+                return;
+            try {
+                const event = JSON.parse(line);
+                if (event.t >= from && event.t <= to)
+                    out.push(event);
+            }
+            catch {
+                // A torn last line — a flush that was killed mid-write — is a
+                // possibility this format accepts by design (the ticket's own
+                // reasoning for NDJSON: "crash-safe by construction"). Skipping it
+                // loses at most one event, never the read.
+            }
+        });
+        rl.on("close", () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        });
+    });
+    return out;
+}
+/**
+ * Every session on disk for one `(packageName, deviceId)`, oldest first.
+ *
+ * A directory scan plus one small `meta.json` read per session — not an
+ * index, and deliberately not: a working app accumulates a handful of
+ * sessions between retention sweeps, not thousands, so this is cheap without
+ * needing to be clever. Out of scope (the ticket's own words): "any query
+ * language over sessions." This is the one lookup the window-fallback tools
+ * need — "which session(s) could this window's data be sitting in" — and no
+ * more.
+ */
+export async function findSessionsForIdentity(root, packageName, deviceId) {
+    let names;
+    try {
+        names = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const prefix = `${sanitize(packageName)}_${sanitize(deviceId)}_`;
+    const out = [];
+    for (const name of names) {
+        if (!name.startsWith(prefix))
+            continue;
+        const dir = path.join(root, name);
+        const meta = await readMeta(dir);
+        if (meta)
+            out.push({ ...meta, dir });
+    }
+    out.sort((a, b) => a.startedAt - b.startedAt);
+    return out;
+}
+/**
+ * GRA-54: every session on disk, for every app and every device — not
+ * scoped to one identity the way `findSessionsForIdentity` is, because
+ * `porthole sessions` exists to answer "which of yesterday's runs was the
+ * one on the Pixel" for someone who does not already know the id scheme,
+ * and `save_moment`/`porthole save` need to pick a session to act on before
+ * an identity is known at all. Newest-started first, matching the CLI's own
+ * "newest first" requirement — a separate question from *which* session is
+ * "current" (the caller's job: this only reads what is on disk).
+ */
+export async function listAllSessions(root) {
+    let names;
+    try {
+        names = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const dir = path.join(root, name);
+        const meta = await readMeta(dir);
+        if (meta)
+            out.push({ ...meta, dir });
+    }
+    out.sort((a, b) => b.startedAt - a.startedAt);
+    return out;
+}
+/**
+ * Bytes on disk for one session directory: `events.ndjson` plus `meta.json`.
+ * Shared with `enforceRetention`'s own sizing (`sessionDirInfo` below) only
+ * in spirit, not in code — that function also needs `updatedAt` and treats a
+ * missing `events.ndjson` as "not a session directory at all" (returns
+ * null), a distinction retention cares about and `porthole sessions` does
+ * not: a session `open()`ed but never yet flushed is still a real row in
+ * that listing, just a 0-or-small-byte one.
+ */
+export async function sessionSizeBytes(dir) {
+    let bytes = 0;
+    try {
+        bytes += (await stat(eventsPath(dir))).size;
+    }
+    catch {
+        // No events flushed yet — a real, if small, state for a just-opened session.
+    }
+    try {
+        bytes += (await stat(metaPath(dir))).size;
+    }
+    catch {
+        // Missing meta.json is odd but not fatal for sizing.
+    }
+    return bytes;
+}
+/**
+ * How much of `[from, to]` fell outside what a merged view (`WindowFill`'s
+ * `coveredFrom`/`coveredTo`) actually covers — the same `clippedMs`
+ * vocabulary `findings` has always reported, now the one function both
+ * `findings` (index.ts) and `save_moment`/`porthole save` (save.ts) call,
+ * rather than two hand-rolled copies that agree until the day one of them
+ * changes and the disagreement is silent (GRA-163's history, repeatedly).
+ *
+ * Deliberately not derived from which events matched — see
+ * `fillWindowFromDisk`'s own doc comment above on why a quiet stretch inside
+ * a fully-recorded session must read as covered, not clipped.
+ */
+export function clippedMsOf(from, to, coveredFrom, coveredTo) {
+    const ms = Math.max(0, to - from);
+    if (coveredFrom === null || coveredTo === null)
+        return { start: ms, end: 0 };
+    return {
+        start: from < coveredFrom ? coveredFrom - from : 0,
+        end: to > coveredTo ? to - coveredTo : 0,
+    };
+}
+/**
+ * The one place "what actually happened in this window" is answered from
+ * both the live in-memory buffer and whatever sessions on disk overlap it —
+ * so `findings`, `what_was_happening` and `timeline` (once `index.ts`'s
+ * `#window-fallback` section calls this) all agree, instead of three
+ * separately hand-rolled merges that drift the way GRA-163's history warns
+ * about.
+ *
+ * **The restart-boundary case, built deliberately with the boundary inside
+ * the window rather than adjacent to it** (this ticket's own instruction):
+ * `sessions.test.ts` asks for a window that starts before an old session's
+ * last event and ends after a new session's first one, with both sessions
+ * present on disk and a live buffer holding only the new session's events —
+ * exactly what "the MCP server was killed and restarted mid-session" (AC1)
+ * or "the app was reinstalled" (the ticket's own motivating scenario)
+ * produce. The assertion is on the *merged* list: both sides present, in
+ * `t` order, no event twice.
+ *
+ * Deduplication key is `(sessionDir, seq)`, not `seq` alone — `seq` is a
+ * monotonic counter that restarts at zero in every process (`EventRing.kt`),
+ * so two different sessions' events can carry the same `seq` and are not
+ * the same event; an event already in `buffered` and *also* already flushed
+ * to the current session's own file (a flush landing between the two reads)
+ * shares both the directory and the `seq`, and is the same event, so it is
+ * kept once. `currentSessionDir` supplies that directory for in-memory
+ * events — pass `device.sessions?.currentDir() ?? null`.
+ */
+export async function fillWindowFromDisk(params) {
+    const seen = new Set();
+    const merged = [];
+    const keyOf = (dir, seq) => `${dir ?? "?"}:${seq}`;
+    const take = (event, dir) => {
+        const key = keyOf(dir, event.seq);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        merged.push(event);
+    };
+    let coveredFrom = null;
+    let coveredTo = null;
+    const widen = (rangeFrom, rangeTo) => {
+        const from = Math.max(params.from, rangeFrom);
+        const to = Math.min(params.to, rangeTo);
+        if (from > to)
+            return; // this range does not actually touch the window
+        coveredFrom = coveredFrom === null ? from : Math.min(coveredFrom, from);
+        coveredTo = coveredTo === null ? to : Math.max(coveredTo, to);
+    };
+    for (const event of params.buffered) {
+        if (event.t < params.from || event.t > params.to)
+            continue;
+        take(event, params.currentSessionDir);
+    }
+    if (params.buffered.length > 0) {
+        widen(params.buffered[0].t, params.buffered[params.buffered.length - 1].t);
+    }
+    if (params.identity) {
+        const sessions = await findSessionsForIdentity(params.root, params.identity.packageName, params.identity.deviceId);
+        for (const session of sessions) {
+            if (session.firstT === null || session.lastT === null)
+                continue;
+            if (session.lastT < params.from || session.firstT > params.to)
+                continue;
+            widen(session.firstT, session.lastT);
+            const fromDisk = await readSessionWindow(session.dir, params.from, params.to);
+            for (const event of fromDisk)
+                take(event, session.dir);
+        }
+    }
+    merged.sort((a, b) => a.t - b.t || a.seq - b.seq);
+    return {
+        events: merged,
+        oldest: merged.length > 0 ? merged[0].t : null,
+        newest: merged.length > 0 ? merged[merged.length - 1].t : null,
+        coveredFrom,
+        coveredTo,
+    };
+}
+/** ~500MB / 7 days: the ticket's own defaults. Configurable via env and the `porthole {}` block once GRA-119 lands a way to carry Gradle config to the MCP server; both are plain numbers here so that wiring is a call-site change, not a rewrite. */
+export const DEFAULT_RETENTION = {
+    maxBytes: 500 * 1024 * 1024,
+    maxAgeMs: 7 * 24 * 60 * 60 * 1000,
+};
+/**
+ * The env half of retention config — `SessionWriter.open()`'s only caller of
+ * `enforceRetention`, so this is where the override actually lands. The
+ * `porthole {}` DSL half (a Gradle-side setting reaching the MCP server) is
+ * explicitly **not** part of this ticket; env vars are the whole mechanism
+ * for now, and are not superseded by the DSL arriving later — that would be
+ * a second source of truth for the same two numbers.
+ *
+ * Missing, empty or malformed values (`""`, `"abc"`, a negative number, `0`)
+ * all fall back to [DEFAULT_RETENTION] rather than producing a retention
+ * policy that prunes everything or nothing by accident — a typo in an env
+ * var should degrade to "the documented default", not to undefined
+ * behaviour.
+ */
+export function retentionOptionsFromEnv() {
+    const maxBytes = parsePositiveInt(process.env.PORTHOLE_SESSIONS_MAX_BYTES);
+    const maxAgeDays = parsePositiveInt(process.env.PORTHOLE_SESSIONS_MAX_AGE_DAYS);
+    return {
+        maxBytes: maxBytes ?? DEFAULT_RETENTION.maxBytes,
+        maxAgeMs: maxAgeDays !== undefined ? maxAgeDays * 24 * 60 * 60 * 1000 : DEFAULT_RETENTION.maxAgeMs,
+    };
+}
+/** A positive integer, or `undefined` for anything that is not one — missing, empty, `NaN`, zero, negative or fractional-but-non-finite input all collapse to "no override". */
+function parsePositiveInt(value) {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+}
+/**
+ * `PORTHOLE_SESSIONS=0` is the documented off switch (README's "Sessions on
+ * disk" section): any other value, including unset, leaves writing on. This
+ * is read fresh on every `open()` call rather than cached, so a test (or a
+ * host that changes its own environment) never has to worry about import
+ * order.
+ */
+export function sessionsEnabled() {
+    return process.env.PORTHOLE_SESSIONS !== "0";
+}
+async function sessionDirInfo(dir) {
+    let bytes = 0;
+    let updatedAt = 0;
+    try {
+        const eventsStat = await stat(eventsPath(dir));
+        bytes += eventsStat.size;
+        updatedAt = eventsStat.mtimeMs;
+    }
+    catch {
+        // No events file at all: not a session directory (or one that was never
+        // written to), either way nothing for retention to weigh.
+        return null;
+    }
+    try {
+        bytes += (await stat(metaPath(dir))).size;
+    }
+    catch {
+        // Missing meta.json is odd but not fatal for sizing.
+    }
+    const meta = await readMeta(dir);
+    // meta.updatedAt is the session's own account of when it was last written;
+    // preferred over the file's mtime because a session that was recreated
+    // (readMeta found nothing so a fresh meta.json was written, but the
+    // underlying events.ndjson survived from an earlier, much older run — not
+    // a real scenario today, but nothing here should quietly rely on it not
+    // happening) would otherwise inherit a misleading age from the wrong file.
+    return { dir, bytes, updatedAt: meta?.updatedAt ?? updatedAt };
+}
+/**
+ * Prunes sessions by both age and total size, oldest-updated first, and
+ * never touches `activeDir` — the session currently being written — no
+ * matter how old or how large it is. That guarantee is the point of taking
+ * `activeDir` as a parameter rather than inferring "in progress" from
+ * `updatedAt` being recent: a session that has been open for hours without a
+ * new event (an idle app) is still the one in progress, and recency of the
+ * last write is exactly the signal retention otherwise uses to decide what
+ * is safe to delete.
+ */
+export async function enforceRetention(root, options = DEFAULT_RETENTION, activeDir = null) {
+    let names;
+    try {
+        names = await readdir(root);
+    }
+    catch {
+        return { prunedDirs: [] };
+    }
+    const infos = [];
+    for (const name of names) {
+        const info = await sessionDirInfo(path.join(root, name));
+        if (info)
+            infos.push(info);
+    }
+    const active = infos.filter((info) => info.dir === activeDir);
+    const prunable = infos.filter((info) => info.dir !== activeDir);
+    prunable.sort((a, b) => a.updatedAt - b.updatedAt);
+    const now = Date.now();
+    const survivors = [];
+    const pruned = [];
+    for (const info of prunable) {
+        if (now - info.updatedAt > options.maxAgeMs) {
+            pruned.push(info.dir);
+        }
+        else {
+            survivors.push(info);
+        }
+    }
+    let total = active.reduce((sum, info) => sum + info.bytes, 0) + survivors.reduce((sum, info) => sum + info.bytes, 0);
+    let i = 0;
+    while (total > options.maxBytes && i < survivors.length) {
+        total -= survivors[i].bytes;
+        pruned.push(survivors[i].dir);
+        i++;
+    }
+    for (const dir of pruned) {
+        await rm(dir, { recursive: true, force: true });
+    }
+    return { prunedDirs: pruned };
+}
+//# sourceMappingURL=sessions.js.map