@cruxy/cli 1.8.1 → 1.10.0

package/dist/onboarding/steps.js

@@ -8,6 +8,118 @@ import { loadProjectInstructions, scaffoldProjectInstructions, } from "../config
  */
 const MAX_KEY_ATTEMPTS = 3;
 const c = (io) => themeForColor(io.color);
+/**
+ * Sign in by approving in a browser — the default path.
+ *
+ * WHY IT IS THE DEFAULT, and why it is not merely a nicer prompt: a pasted key
+ * is minted through the admin issue-key route, which cannot produce a
+ * subscription credential — asking for one there is explicitly refused. So every
+ * pasted CLI key lands in the metered `apikey` bucket with no token pool, while
+ * the same human's web chat and desktop draw on their plan. One human, two
+ * budgets. The device flow mints through the login issuer, which is the only
+ * path to the subscription bucket, so the credential it produces draws on the
+ * pool the user already has.
+ *
+ * THE KEY IS NOT RE-VALIDATED. The gateway minted it seconds ago and returned it
+ * over the same connection; a `validateKey` call here would spend a real,
+ * billable request to re-prove a fact we were just told — against the very pool
+ * this step exists to establish. The paste path validates because there a key is
+ * an unverified claim by the user; here it is the gateway's own answer.
+ *
+ * Every outcome is reported, never thrown: a denial and an expiry are the flow
+ * working correctly, and both leave the existing credential untouched.
+ */
+export async function deviceLoginStep(io, deps, provider) {
+    const col = c(io);
+    if (!deps.deviceLogin)
+        return { status: "skipped" };
+    const outcome = await deps.deviceLogin(deviceIO(io));
+    switch (outcome.status) {
+        case "ok": {
+            deps.writeCredentialWithMeta(provider, outcome.apiKey, {
+                ...(outcome.expiresAt !== undefined
+                    ? { expiresAt: outcome.expiresAt }
+                    : {}),
+                ...(outcome.keyId !== undefined ? { keyId: outcome.keyId } : {}),
+                source: "device",
+            });
+            io.write(`${col.success(col.glyph.success)} signed in — credential saved to ~/.cruxy\n`);
+            if (outcome.expiresAt) {
+                io.write(col.muted(`  it expires on ${formatExpiry(outcome.expiresAt)}; run \`cruxy login\` again before then.\n`));
+            }
+            return {
+                status: "ok",
+                apiKey: outcome.apiKey,
+                ...(outcome.expiresAt !== undefined
+                    ? { expiresAt: outcome.expiresAt }
+                    : {}),
+                ...(outcome.keyId !== undefined ? { keyId: outcome.keyId } : {}),
+            };
+        }
+        case "denied":
+            io.write(`${col.danger(col.glyph.failure)} the sign-in was declined in the browser.\n`);
+            return { status: "failed", message: "sign-in declined" };
+        case "expired":
+            io.write(`${col.danger(col.glyph.failure)} the code expired before it was approved.\n`);
+            return {
+                status: "failed",
+                message: "the code expired — run `cruxy login` to get a new one",
+            };
+        case "invalid":
+            // The gateway collapses four causes into one code on purpose and tells us
+            // nothing about which; all four are answered by starting over.
+            io.write(`${col.danger(col.glyph.failure)} that sign-in could not be completed.\n`);
+            return {
+                status: "failed",
+                message: "sign-in could not be completed — run `cruxy login` to retry",
+            };
+        case "unreachable":
+            io.write(`${col.danger(col.glyph.failure)} couldn't reach the gateway to sign in.\n`);
+            return { status: "failed", message: outcome.message };
+    }
+}
+/** Render the device flow's two messages onto the onboarding IO. */
+function deviceIO(io) {
+    const col = c(io);
+    let lastNote = "";
+    return {
+        prompt: (session) => {
+            const link = session.verificationUriComplete ?? session.verificationUri;
+            io.write(`\nTo sign in, open ${col.accent(link)}\n` +
+                `and enter the code ${col.strong(session.userCode)}\n\n` +
+                col.muted(`waiting for approval (expires in ${humanDuration(session.expiresInMs)})…\n`));
+        },
+        waiting: (info) => {
+            // Only the throttle is worth saying out loud, and only once: a line per
+            // poll would scroll a quiet wait off the screen, and "still waiting" adds
+            // nothing to the "waiting for approval" already on it.
+            if (!info.throttled || lastNote === "throttled")
+                return;
+            lastNote = "throttled";
+            io.write(col.muted("  the gateway asked us to slow down; still waiting…\n"));
+        },
+    };
+}
+/** "2 days", "9 minutes" — coarse on purpose; this is a reassurance, not a timer. */
+function humanDuration(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 1)
+        return "less than a minute";
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? "" : "s"}`;
+    const days = Math.round(hours / 24);
+    return `${days} day${days === 1 ? "" : "s"}`;
+}
+/** The date part of an RFC 3339 expiry, or the raw string if it will not parse. */
+function formatExpiry(expiresAt) {
+    const at = Date.parse(expiresAt);
+    if (Number.isNaN(at))
+        return expiresAt;
+    return new Date(at).toISOString().slice(0, 10);
+}
 /**
  * Acquire and persist a provider key: print the create-key URL, read it masked,
  * validate it live, and **only then** write it to the credentials store. Loops on

package/dist/render/limits-report.js

@@ -0,0 +1,213 @@
+import { compactTokens } from "./units.js";
+import { buildLimitsSummary } from "./limits-view.js";
+/**
+ * Rendering `cruxy limits` (cli#138) — the session-less half of the P9 reading.
+ *
+ * WHY A COMMAND AND NOT A COLUMN IN `cruxy usage`. The two answer questions with
+ * no common denominator, and joining them produces a number that reads as
+ * authoritative while being about two different things: `usage/store.ts` counts
+ * this machine's last FIFTY RUNS — a count, not a duration — while the pool is a
+ * calendar month and a trailing 12h window, already inclusive of every other
+ * surface on the account. The gap is not a rounding error. A credential minted
+ * seconds earlier, with zero local runs behind it, reported 63% of its month
+ * already drawn from web chat and desktop; any ratio over those two numerators
+ * would have been wrong by nearly its whole value on day one.
+ *
+ * So `cruxy usage` keeps its local-only guarantee and this command makes the
+ * call. THE COMMAND SPLIT IS THE BOUNDARY, and it is worth saying plainly that
+ * the no-phone-home guard is not: that guard scans a named list of files, this
+ * file is deliberately not on it, and a green run of it proves nothing whatever
+ * about a file it was never pointed at. What keeps `cruxy usage` local is that
+ * the network lives in a different command, not that a test noticed.
+ *
+ * IT NAMES THE WINDOW RATHER THAN THE ABSTRACTION. The rail picks one window
+ * because it has room for one bar, and `session-budget.ts` picks one because
+ * admission has to spend against one — both are right, and both are choices a
+ * SURFACE has to make. A command has room for neither excuse: it prints
+ * `monthly` and `12h burst` by name, in the vocabulary `/budget` already uses,
+ * because "the binding window" is a phrase that at Free tier (where
+ * `burst.cap === monthly.cap`) resolves to the same window essentially always —
+ * an abstraction that never varies, costing the reader the one fact they came
+ * for.
+ */
+/** Bar width. Wider than the rail's twelve cells; a command has the columns. */
+const BAR_CELLS = 24;
+/** The label each window goes by here — see the module comment on naming. */
+const WINDOW_LABEL = {
+    month: "monthly",
+    burst: "12h burst",
+};
+/** Widest label, so every row's bar starts in the same column. */
+const LABEL_COLS = Math.max(...Object.values(WINDOW_LABEL).map((l) => l.length));
+function bar(theme, fraction) {
+    const filled = Math.round(Math.min(1, Math.max(0, fraction)) * BAR_CELLS);
+    return (theme.glyph.barFilled.repeat(filled) +
+        theme.glyph.barEmpty.repeat(BAR_CELLS - filled));
+}
+/**
+ * A percentage, right-aligned to the width of "100%", so the figures beside it
+ * start in the same column on every row. A ragged column reads as two unrelated
+ * numbers rather than one comparison, which is the whole point of stacking the
+ * windows.
+ */
+function pct(fraction) {
+    return `${Math.round(fraction * 100)}%`.padStart(4);
+}
+/** 27.77 → "$27.77", 29 → "$29". Same rule the panel uses. */
+function usd(n) {
+    return Number.isInteger(n) ? `$${n}` : `$${n.toFixed(2)}`;
+}
+/** "in 18d" / "in 4h", or nothing at all when there is no reset to state. */
+function resetLabel(iso, now) {
+    if (!iso)
+        return undefined;
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return undefined;
+    const ms = at - now;
+    if (ms <= 0)
+        return "resets now";
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 60)
+        return `resets in ${Math.max(1, minutes)}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `resets in ${hours}h`;
+    return `resets in ${Math.floor(hours / 24)}d`;
+}
+/**
+ * How long ago a reading was taken, as a whole sentence.
+ *
+ * "just now" is a real case here and is not one for the rail: the panel only
+ * ever says this past a five-minute staleness threshold, while a command probes
+ * and prints in the same breath. Rounding that up to "1m ago" would age a
+ * reading by a minute it did not have.
+ */
+function readAgeLine(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 1)
+        return "read just now";
+    if (minutes < 60)
+        return `read ${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    return hours < 24
+        ? `read ${hours}h ago`
+        : `read ${Math.floor(hours / 24)}d ago`;
+}
+/** One window: name, bar, percentage, the figures, and its reset if it has one. */
+function windowLine(theme, w, now) {
+    const style = w.tone === "danger"
+        ? theme.danger
+        : w.tone === "warn"
+            ? theme.warning
+            : theme.strong;
+    const label = WINDOW_LABEL[w.key].padEnd(LABEL_COLS);
+    const figures = `${compactTokens(w.window.used)} / ${compactTokens(w.window.cap)}`;
+    const reset = resetLabel(w.window.resetsAt, now);
+    return (`  ${theme.strong(label)} ${style(bar(theme, w.fraction))} ` +
+        `${style(pct(w.fraction))}  ${theme.muted(figures)}` +
+        (reset ? theme.muted(`${theme.sep}${reset}`) : ""));
+}
+function spendCapLine(theme, label, cap) {
+    const name = label === "ws" ? "workspace spend cap" : "key spend cap";
+    return theme.muted(`  ${name}  ${usd(cap.remaining)} of ${usd(cap.cap)} left`);
+}
+/**
+ * The whole report, or the one honest sentence when there is no reading.
+ *
+ * The three not-a-reading states are said three ways, on the same discipline the
+ * panel keeps: "still asking" must not read as "no limits", and neither may read
+ * as "your key is bad". A command exits after saying it, so each one also gets
+ * the next step rather than leaving the user to infer it from four words.
+ */
+export function limitsReportLines(theme, state, now = Date.now()) {
+    if (state.status === "pending") {
+        return [theme.muted("the limits reading has not arrived yet")];
+    }
+    if (state.status === "error") {
+        switch (state.reason) {
+            case "unauthenticated":
+                return [
+                    theme.warning("not signed in"),
+                    theme.muted("run `cruxy login` to sign in"),
+                ];
+            // A different FACT from "not signed in", and the fact is the point: this
+            // user's setup was right and simply aged out. Sending them to look for
+            // what they configured wrong would be sending them after nothing.
+            case "expired":
+                return [
+                    theme.warning("your sign-in has expired"),
+                    theme.muted("run `cruxy login` to sign in again"),
+                ];
+            // The gateway ANSWERED — it has no limits to report. Telling this user to
+            // check their network would be the wrong errand entirely.
+            case "unsupported":
+                return [
+                    theme.muted("this gateway does not report limits"),
+                    theme.muted("nothing here is wrong with your setup or your network"),
+                ];
+            case "unreachable":
+                return [
+                    theme.warning("could not reach the gateway"),
+                    theme.muted("check your connection and try again"),
+                ];
+        }
+    }
+    const s = buildLimitsSummary(state.reading, now);
+    const lines = [
+        `${theme.heading(s.tier)} ${theme.muted(`${theme.glyph.sep} ${s.bucket}`)}`,
+    ];
+    if (s.windows.length > 0) {
+        lines.push("");
+        for (const w of s.windows)
+            lines.push(windowLine(theme, w, now));
+        // The unit, once, under the windows it applies to. Named because a bare
+        // "942.8k" invites being read as requests or as raw tokens, and it is
+        // neither: it is `(billable_input + output) × tier multiplier`, the unit the
+        // meter counts in and the only one anything enforces.
+        lines.push(theme.muted(`  ${" ".repeat(LABEL_COLS)} weighted tokens`));
+    }
+    // Why there is nothing to draw, for the shapes that have nothing. Stated, not
+    // omitted: an empty section reads as a figure that failed to load.
+    if (s.noAllowance) {
+        lines.push("");
+        lines.push(`  ${theme.muted(s.noAllowance)}`);
+    }
+    // What this credential could have and does not (cli#263). An offer, not a
+    // correction — a deliberate `--paste` user is on an apikey on purpose and
+    // should be able to read this line and correctly ignore it.
+    for (const note of s.notes) {
+        lines.push(`  ${theme.muted(note)}`);
+    }
+    const pool = s.budget;
+    if (pool.kind === "pool") {
+        // Both stated whenever they exist. The rail shows them only when the pool is
+        // already low, because it has five lines; this has a terminal, and "what can
+        // I still run" is a fair question before the answer becomes urgent.
+        if (pool.mira) {
+            lines.push(theme.muted(`  mira  ${compactTokens(pool.mira.remaining)} of ${compactTokens(pool.mira.cap)} requests left${theme.sep}${pool.mira.window}`));
+        }
+        if (pool.blockedModels.length > 0) {
+            lines.push(theme.danger(`  refusing: ${pool.blockedModels.join(", ")}`));
+        }
+    }
+    if (pool.kind === "credits") {
+        lines.push("");
+        lines.push(`  ${theme.strong(usd(pool.remaining))} ${theme.muted(`of ${usd(pool.granted)} left`)}`);
+        const reset = resetLabel(pool.resetsAt, now);
+        if (reset)
+            lines.push(theme.muted(`  ${reset}`));
+    }
+    if (s.rpm) {
+        lines.push(theme.muted(`  rate  ${s.rpm.remaining} of ${s.rpm.limit} requests/min`));
+    }
+    for (const { label, cap } of s.spendCaps) {
+        lines.push(spendCapLine(theme, label, cap));
+    }
+    // Always, not only past a staleness threshold. The rail is repainting and can
+    // afford to stay quiet while a figure is fresh; a command prints once and is
+    // read later, so the reading's age is part of what it said.
+    lines.push("");
+    lines.push(theme.muted(readAgeLine(s.ageMs)));
+    return lines;
+}

package/dist/render/limits-view.js

@@ -0,0 +1,125 @@
+import { usedFraction } from "../limits/index.js";
+/**
+ * A metered credential's one missing capability, stated as availability
+ * (cli#263).
+ *
+ * KEYED OFF `bucket`, NOT off a missing credential expiry. The two look
+ * interchangeable and answer different questions: `bucket === "apikey"` says
+ * *this credential type cannot have a pool*, while a missing `keyMeta.expiresAt`
+ * says *we do not know this key's lifetime*. Absence is load-bearing for the
+ * second — every pre-existing key has no entry, and an admin-minted key
+ * genuinely never expires, so `config/credentials.ts` rests on absence meaning
+ * "unknown lifetime, never expired". Reusing it here would overload the one
+ * invariant the expiry design is built on, to answer a question `bucket` already
+ * answers exactly.
+ *
+ * AND IT IS AN OFFER, NOT A CORRECTION. `--paste` exists for the air-gapped
+ * machine and the deliberate long-lived admin key, and those users are on
+ * `apikey` on purpose. "Your key is wrong" would be false for them; a line that
+ * says what logging in ADDS is true for everyone and safely ignorable by anyone
+ * who does not want it. It is also not a start-up nag: `cli/commands/run.ts`
+ * owns the pre-session line for the expiry warning, and a second one there would
+ * teach people to skip both.
+ *
+ * Returns `undefined` the moment the bucket is anything else — including an
+ * `apikey` whose response this build could not read, where the honest answer is
+ * to advise nothing rather than to advise from a shape we did not understand.
+ */
+export function poolAvailabilityNote(reading) {
+    if (reading.bucket !== "apikey")
+        return undefined;
+    if (reading.budget.kind !== "metered")
+        return undefined;
+    return "cruxy login adds a pool";
+}
+/** The tone a window's state maps to. `low` and `blocked` are different acts. */
+function toneFor(state) {
+    if (state === "blocked")
+        return "danger";
+    if (state === "low")
+        return "warn";
+    return "normal";
+}
+/** A capped window, or nothing — never a fraction over a cap that isn't one. */
+function toMeter(key, window, poolState) {
+    if (!window)
+        return undefined;
+    const fraction = usedFraction(window);
+    if (fraction === undefined)
+        return undefined;
+    return { key, window, fraction, tone: toneFor(window.state ?? poolState) };
+}
+/**
+ * Resolve one reading into {@link LimitsSummary}.
+ *
+ * Pure and synchronous: every value is read off the reading it is handed. The
+ * network already happened in `limits/cache.ts`, and the tri-state that wraps
+ * this (`pending` / `error` / `ready`) is deliberately NOT reduced here — a
+ * summary is what a *reading* means, and a caller with no reading has a
+ * different thing to say, in words that differ per surface.
+ */
+export function buildLimitsSummary(reading, now) {
+    const budget = reading.budget;
+    const windows = [];
+    let noAllowance;
+    switch (budget.kind) {
+        case "pool": {
+            const month = toMeter("month", budget.monthly, budget.state);
+            const burst = toMeter("burst", budget.burst, budget.state);
+            if (month)
+                windows.push(month);
+            if (burst)
+                windows.push(burst);
+            // Unreachable through `reduceLimits` (an enforced pool with no readable
+            // window reduces to `unknown`), but the type permits it and inventing a
+            // fraction is the one thing no surface here may do while being defensive.
+            if (windows.length === 0)
+                noAllowance = "figures not reported";
+            break;
+        }
+        // Enterprise: a POSITIVE statement that there is no ceiling. Distinct from
+        // `unknown` below, and the distinction is the one that matters most in this
+        // file — "we lost track of your ceiling" rendered as "you have none" tells
+        // someone they are safe to spend at the exact moment we cannot say.
+        case "unenforced":
+            noAllowance = "pool not enforced";
+            break;
+        case "metered":
+            noAllowance = "no pool cap";
+            break;
+        case "credits":
+            // A dollar pool, and the only allowance that is not weighted tokens. It
+            // stays off `windows` for that reason: those are token windows, and a
+            // renderer that iterated them would print dollars in the tokens' unit.
+            break;
+        case "unknown":
+            noAllowance = "budget not reported";
+            break;
+    }
+    const spendCaps = [];
+    if (reading.keySpendCap)
+        spendCaps.push({ label: "key", cap: reading.keySpendCap });
+    if (reading.workspaceSpendCap)
+        spendCaps.push({ label: "ws", cap: reading.workspaceSpendCap });
+    const note = poolAvailabilityNote(reading);
+    return {
+        tier: reading.tier,
+        bucket: reading.bucket,
+        budget,
+        windows,
+        ...(noAllowance !== undefined ? { noAllowance } : {}),
+        notes: note ? [note] : [],
+        spendCaps,
+        // Only where it is the whole story. A rate limit beside a real allowance
+        // reads as part of it; beside a metered key's absence, it is the ceiling.
+        ...(budget.kind === "metered" && reading.chat
+            ? {
+                rpm: {
+                    remaining: reading.chat.perKey.remaining,
+                    limit: reading.chat.perKey.limit,
+                },
+            }
+            : {}),
+        ageMs: now - reading.readAt,
+    };
+}

package/dist/sandbox/service.js

@@ -53,6 +53,15 @@ export class SandboxService {
      * (surfacing the pull via U.4), then delegates to the runtime. A container
      * that fails to start throws a coded error; an ordinary non-zero command exit
      * comes back as a normal {@link ExecResult} — exit code is truth.
+     *
+     * ONE POLICY PER SESSION, not per action. `SandboxRuntime.exec` takes a policy
+     * argument and this one does not: {@link create} resolved it once from config
+     * + cwd and every call here runs under that same {@link IsolationPolicy}. So a
+     * caller cannot tighten the box for a particular command — no argument does
+     * it, and reaching around to the runtime would bypass the image memoization.
+     * Per-action confinement is a new seam here, not a parameter that already
+     * exists; recorded because the shape of `SandboxRuntime.exec` suggests
+     * otherwise at a glance.
      */
     async exec(command, opts) {
         await this.ensureImage();

package/dist/sandbox/types.js

@@ -9,6 +9,21 @@
  * sandbox contains what an approved command is able to do; it does not replace
  * the decision to run it.
  *
+ * ── It bounds the EXECUTION surface, and only that ──
+ * Worth saying in the words that get misread: this is not "the session runs
+ * confined." `ToolContext.sandbox` is consulted at exactly two call sites —
+ * `tools/shell/exec.ts` (`execShell`) and `testing/run-tests-tool.ts` — so
+ * `run_command` and `run_tests` are the whole of what a container ever bounds.
+ * `write_file`, `edit_file`, and `apply_patch` call the filesystem directly and
+ * run on the HOST in every mode, sandbox or no sandbox; their bound is the C.26
+ * path confinement plus the C.32 checkpoint, not this boundary.
+ *
+ * That distinction is load-bearing wherever a rule is stated in terms of
+ * confinement: a slogan like "an auto-approving mode runs confined" reads as
+ * covering file writes and does not. See the cli#194 section in
+ * `approval/classify.ts` for what a mode rule keyed on this boundary would and
+ * would not have bought.
+ *
  * Execution is abstracted behind {@link SandboxRuntime} (Docker ships; podman /
  * none slot in without touching call sites), and the neutral {@link ExecResult}
  * matches what host execution conceptually returns so `run_command`/`run_tests`

package/dist/session/index.js

@@ -8,6 +8,7 @@
  *  - `log.ts` — the writer: one line per event, `0600`, non-fatal on failure;
  *  - `replay.ts` — the fold back to state, tolerant of torn/unknown lines;
  *  - `list.ts` — what the picker and the TUI sidebar both read;
+ *  - `prune.ts` — retention: what the tree is allowed to keep (#257);
  *  - `resume.ts` — `--resume <id>` and the bare-`--resume` picker;
  *  - `paths.ts` — the layout, including the subtrees reserved for P3+.
  */
@@ -16,6 +17,7 @@ export { SessionLog } from "./log.js";
 export { defaultExportName, exportMarkdown, } from "./export.js";
 export { foldEvents, readEvents, readMeta, replaySession } from "./replay.js";
 export { redactMessages } from "./redact.js";
-export { findSession, isAmbiguous, listSessionRefs, listSessions, matchSessionRefs, summarizeSession, } from "./list.js";
+export { findSession, isAmbiguous, listSessionRefs, listSessions, matchSessionRefs, sessionFilesByRecency, summarizeSession, } from "./list.js";
+export { pruneSessions, } from "./prune.js";
 export { cwdMismatchWarning, describeSession, loadResume, priorDirectoriesWarning, relativeAge, resolveSessionId, resumeById, resumePicker, shortId, PICKER_LIMIT, } from "./resume.js";
 export { KNOWN_EVENT_KINDS, SESSION_FILE_VERSION, ResumedEventSchema, SessionEventSchema, SessionMetaSchema, } from "./types.js";

package/dist/session/list.js

@@ -31,7 +31,7 @@ function toTitle(text) {
  * picker asks for ten". It was not. {@link listSessions} summarized EVERY file
  * and sliced afterwards, so the limit bounded the rows and not the work; a
  * project of 200 sessions paid 200 full parses to show 10. The limit now bounds
- * the work (see {@link sessionRefsByRecency}), which is what finally makes that
+ * the work (see {@link sessionFilesByRecency}), which is what finally makes that
  * sentence true. A sidecar index is still the answer if per-file cost ever
  * stops being acceptable — but the ordering fix had to come first, because an
  * index would have made the same mistake faster.
@@ -108,8 +108,19 @@ export function summarizeSession(file) {
  * Missing directory → empty list (not an error: no sessions yet is normal). A
  * file that vanishes between the `readdir` and the `stat` is skipped rather
  * than throwing — listing races an active session by definition.
+ *
+ * EXPORTED for `prune.ts` (#257), which needs exactly this and nothing more:
+ * mtime ordering is what both bounds consume, and a second scan in the pruner
+ * would reintroduce the duplication #255 removed. It is the ONLY directory walk
+ * over a project's sessions — keep it that way.
+ *
+ * The `.jsonl` filter and the `isFile` test are load-bearing beyond tidiness.
+ * `subagents/` lives in this same directory (reserved by `paths.ts` for #172
+ * item 1), `statSync` succeeds on a directory, and everything this returns is
+ * something prune will consider deleting. Anything added here is added to that
+ * set.
  */
-function sessionRefsByRecency(cwd) {
+export function sessionFilesByRecency(cwd) {
     const dir = projectDir(cwd);
     let names;
     try {
@@ -124,7 +135,10 @@ function sessionRefsByRecency(cwd) {
             continue;
         const file = path.join(dir, name);
         try {
-            files.push({ file, mtimeMs: statSync(file).mtimeMs });
+            const stat = statSync(file);
+            if (!stat.isFile())
+                continue;
+            files.push({ file, mtimeMs: stat.mtimeMs, size: stat.size });
         }
         catch {
             continue; // deleted mid-listing
@@ -140,7 +154,7 @@ function sessionRefsByRecency(cwd) {
  * capped at `limit`.
  *
  * `limit` bounds the WORK, not just the rows. Files are ordered by mtime first
- * (cheap — see {@link sessionRefsByRecency}) and summarized one at a time until
+ * (cheap — see {@link sessionFilesByRecency}) and summarized one at a time until
  * `limit` valid summaries exist, so the picker asking for ten reads ten files
  * and not two hundred.
  *
@@ -153,7 +167,7 @@ function sessionRefsByRecency(cwd) {
  */
 export function listSessions(cwd, limit = Infinity) {
     const summaries = [];
-    for (const { file } of sessionRefsByRecency(cwd)) {
+    for (const { file } of sessionFilesByRecency(cwd)) {
         if (summaries.length >= limit)
             break;
         const summary = summarizeSession(file);
@@ -178,7 +192,7 @@ export function listSessions(cwd, limit = Infinity) {
  */
 export function listSessionRefs(cwd) {
     const refs = [];
-    for (const { file, mtimeMs } of sessionRefsByRecency(cwd)) {
+    for (const { file, mtimeMs } of sessionFilesByRecency(cwd)) {
         const meta = readMeta(file);
         if (meta)
             refs.push({ sessionId: meta.sessionId, file, mtimeMs });