@cruxy/cli 1.9.0 → 1.10.0

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 });

package/dist/session/log.js

@@ -1,28 +1,46 @@
 import { appendFileSync, mkdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { APP_VERSION } from "../constants.js";
+import { formatBytes } from "../utils/disk.js";
 import { sessionFile } from "./paths.js";
+import { pruneSessions } from "./prune.js";
 import { SESSION_FILE_VERSION, } from "./types.js";
+/**
+ * How many pruned sessions is worth telling the user about unprompted.
+ *
+ * Retention on an existing install is a one-off cliff: every build so far had
+ * none, so the first prune after upgrading can remove months at once. That
+ * should not happen silently. Steady-state prunes remove one or two files and
+ * stay at `debug`, where they belong.
+ */
+const PRUNE_NOTICE_THRESHOLD = 10;
 export class SessionLog {
     file;
     logger;
     currentRunId;
     /** Set once a write fails: the log goes inert rather than warning per turn. */
     broken = false;
+    /**
+     * A NEW session's `meta` line, held until the session records something.
+     * Null on a reopen (the file already has its meta) and null again the moment
+     * it is flushed — see {@link write}.
+     */
+    pendingMeta = null;
     constructor(file, opts) {
         this.file = file;
         this.logger = opts.logger;
         this.currentRunId = opts.currentRunId;
     }
     /**
-     * Open (or create) a session log.
+     * Open a session log. WRITES NOTHING for a new session — see the note on the
+     * class about why the file no longer exists before the conversation does.
      *
-     * A NEW file gets its `meta` line. Reopening an existing one (a `--resume`)
-     * still does NOT get a second `meta` — that ruling is unchanged and is the
-     * reason this method has always branched: `meta` describes where and when the
-     * conversation began, and a second copy written from wherever it was resumed
-     * would make "the session's directory" ambiguous. Replay takes the first
-     * `meta`, so a duplicate could only ever mislead a later reader.
+     * A NEW session gets its `meta` line BUFFERED. Reopening an existing one (a
+     * `--resume`) still does NOT get a second `meta` — that ruling is unchanged
+     * and is the reason this method has always branched: `meta` describes where
+     * and when the conversation began, and a second copy written from wherever it
+     * was resumed would make "the session's directory" ambiguous. Replay takes
+     * the first `meta`, so a duplicate could only ever mislead a later reader.
      *
      * What a reopen gets instead is a `resumed` event (#172 item 2). It carries
      * the directory this run is in, which is the fact that used to vanish: a
@@ -31,16 +49,33 @@ export class SessionLog {
      * file forgot immediately. `meta` stays singular and authoritative; the
      * reopen is a separate kind, and no reader can confuse the two.
      *
-     * Returns `null` when a new log cannot be created at all — the caller then
-     * runs without persistence rather than failing, exactly as a corrupt usage
-     * store is survivable. A reopen still never returns null: the `resumed` write
-     * is now the first append, and a write problem there warns and goes inert
-     * exactly as any other failed append does. A session that cannot record its
-     * own reopen is not a session worth refusing to continue.
+     * The reopen write stays EAGER, and deliberately: a reopen is a fact about a
+     * conversation that already exists on disk, and `tree.test.ts` pins that it
+     * lifts a resumed session to the top of the picker with nothing said to it.
+     * Deferring it would quietly undo that.
+     *
+     * WHAT A FRESH OPEN NO LONGER TELLS YOU. It used to return `null` when the
+     * meta write failed, which is how the caller learned up front that
+     * persistence was dead. Nothing is written now, so there is nothing to fail:
+     * an unwritable home surfaces on the FIRST append instead, as one warning,
+     * and the session continues in memory. That is not a new tolerance — it is
+     * exactly how the reopen path has always behaved ("a session that cannot
+     * record its own reopen is not a session worth refusing to continue"), now
+     * applied to both branches rather than one.
+     *
+     * The `| null` in the signature is kept for the next thing to land here — a
+     * `sessions.enabled: false` that declines to record at all (#257) — rather
+     * than churning every call site twice.
      */
     static open(opts) {
+        // `sessions.enabled: false` — record nothing. The session runs in memory,
+        // which is the same degraded mode an unwritable home produces, reached on
+        // purpose. Every consumer already treats a missing recorder as normal.
+        if (opts.sessions?.enabled === false)
+            return null;
         const file = opts.file ?? sessionFile(opts.cwd, opts.sessionId);
         const log = new SessionLog(file, opts);
+        log.pruneOnce(opts);
         if (hasContent(file)) {
             log.write({
                 kind: "resumed",
@@ -51,7 +86,10 @@ export class SessionLog {
             });
             return log;
         }
-        const ok = log.write({
+        // Buffered, not written. `startedAt` is stamped HERE rather than at flush:
+        // it means "when this conversation began", and the session began when it
+        // was opened, not when the user got around to saying something.
+        log.pendingMeta = {
             kind: "meta",
             version: SESSION_FILE_VERSION,
             sessionId: opts.sessionId,
@@ -61,8 +99,8 @@ export class SessionLog {
             cliVersion: APP_VERSION,
             ...(opts.provider !== undefined ? { provider: opts.provider } : {}),
             ...(opts.model !== undefined ? { model: opts.model } : {}),
-        });
-        return ok ? log : null;
+        };
+        return log;
     }
     /** Messages appended to the history since the last event. */
     append(messages) {
@@ -99,8 +137,11 @@ export class SessionLog {
     }
     /**
      * One turn's token usage. Copied here rather than referenced, because the
-     * usage store keeps only its newest 50 runs while sessions are kept
-     * indefinitely — see the note on `UsageEventSchema`.
+     * usage store keeps only its newest 50 runs while a session keeps its own
+     * for as long as the session survives `sessions.retention` — see the note on
+     * `UsageEventSchema`. (That used to say "indefinitely", which was true until
+     * #257 gave sessions a bound; the two stores still expire independently, and
+     * the copy is still what makes a restored session's numbers whole.)
      */
     usage(inputTokens, outputTokens) {
         this.write({
@@ -130,18 +171,76 @@ export class SessionLog {
             count,
         });
     }
+    /**
+     * Enforce retention for this project, once, as this session opens.
+     *
+     * ORDERING: before the `resumed` write and before any meta flush, so the
+     * count cap is applied to the sessions that were there BEFORE this one and a
+     * fresh session never has to compete with itself for a slot. On a resume the
+     * file already exists and is explicitly excluded by id.
+     *
+     * Skipped entirely when the `file` seam is in use — see the note on
+     * {@link SessionLogOptions.sessions}.
+     */
+    pruneOnce(opts) {
+        if (!opts.sessions || opts.file !== undefined)
+            return;
+        let result;
+        try {
+            result = pruneSessions(opts.cwd, {
+                sessions: opts.sessions,
+                activeSessionId: opts.sessionId,
+            });
+        }
+        catch (err) {
+            // Retention is housekeeping. It does not get to fail a session.
+            this.logger?.debug(`session retention skipped: ${err.message}`);
+            return;
+        }
+        if (result.removed.length === 0)
+            return;
+        const line = `pruned ${result.removed.length} session${result.removed.length === 1 ? "" : "s"} ` +
+            `(${formatBytes(result.bytesFreed)}) past sessions.retention/maxAgeDays`;
+        if (result.removed.length >= PRUNE_NOTICE_THRESHOLD) {
+            this.logger?.info(`${line} — see \`cruxy sessions\``);
+        }
+        else {
+            this.logger?.debug(line);
+        }
+    }
     runId() {
         const id = this.currentRunId?.();
         return id === undefined ? {} : { runId: id };
     }
     /**
-     * Append one event as a single line. Returns whether it landed. The first
-     * failure warns and latches `broken`, so a persistent problem (a full disk)
-     * produces one diagnostic rather than one per turn.
+     * Record one event, flushing a buffered `meta` ahead of it.
+     *
+     * This is where a new session's file comes into existence: the first event to
+     * reach here brings the `meta` line with it, so the on-disk order is exactly
+     * what it always was and no reader can observe the difference.
+     *
+     * `pendingMeta` is cleared BEFORE the write is attempted. If the meta write
+     * fails, `broken` latches and every later event is refused — leaving the meta
+     * queued for a retry would let it land AFTER events it is supposed to
+     * precede, which is the one ordering the format depends on.
      */
     write(event) {
         if (this.broken)
             return false;
+        const meta = this.pendingMeta;
+        if (meta !== null) {
+            this.pendingMeta = null;
+            if (!this.writeLine(meta))
+                return false;
+        }
+        return this.writeLine(event);
+    }
+    /**
+     * Append one event as a single line. Returns whether it landed. The first
+     * failure warns and latches `broken`, so a persistent problem (a full disk)
+     * produces one diagnostic rather than one per turn.
+     */
+    writeLine(event) {
         try {
             mkdirSync(path.dirname(this.file), { recursive: true });
             // `mode` applies only when the file is created — 0600 from the first

package/dist/session/prune.js

@@ -0,0 +1,106 @@
+import { unlinkSync } from "node:fs";
+import path from "node:path";
+import { SESSION_RETENTION_FLOOR, } from "../config/index.js";
+import { sessionFilesByRecency } from "./list.js";
+import { SESSION_FILE_EXT } from "./paths.js";
+/** `<sessionId>.jsonl` → `<sessionId>`. */
+function idOf(file) {
+    return path.basename(file, SESSION_FILE_EXT);
+}
+/**
+ * Enforce `sessions.retention` and `sessions.maxAgeDays` on one project.
+ *
+ * Age is the primary bound and is measured on MTIME, never on
+ * `meta.startedAt`: a conversation begun forty days ago and resumed this
+ * morning is live, and an age check on when it BEGAN would delete it out from
+ * under the user. mtime is also the field the scan already carries, so the
+ * correct rule is the cheap one.
+ *
+ * The count cap is the backstop, applied by position in the same
+ * newest-first ordering. It exists because age alone does not protect a
+ * directory where someone runs forty sessions a day.
+ *
+ * Never throws. A file that cannot be unlinked is counted in `failed` and the
+ * sweep continues — retention failing is not a reason to take a session down,
+ * exactly as a failed session write is not.
+ */
+export function pruneSessions(cwd, opts) {
+    const result = {
+        removed: [],
+        kept: 0,
+        bytesFreed: 0,
+        failed: 0,
+    };
+    if (!opts.sessions.enabled)
+        return result;
+    // Defensive, mirroring `usage/store.ts`: the schema rejects anything below
+    // the floor, but this is also reachable with a hand-built config.
+    const retention = Math.max(SESSION_RETENTION_FLOOR, Math.floor(opts.sessions.retention));
+    const now = opts.now ?? Date.now();
+    const cutoff = now - opts.sessions.maxAgeDays * 24 * 60 * 60 * 1000;
+    // Newest first. Every file here ends in `.jsonl` and is a regular file — see
+    // the note on the scan about why `subagents/` depends on that.
+    const files = sessionFilesByRecency(cwd);
+    for (const [index, ref] of files.entries()) {
+        const sessionId = idOf(ref.file);
+        // WHY THE FILENAME IS TRUSTED HERE, when `listSessionRefs` refuses to.
+        // That refusal is about what may be OFFERED: a session resolvable by
+        // filename but unloadable for want of a meta line is a `--resume` that
+        // fails after the user picked it. This is the opposite question. Being
+        // conservative about what to DELETE and permissive about what to offer are
+        // opposite failure modes, and the cheap answer is the safe one on this
+        // side — at worst a filename that does not match the meta spares a file
+        // that could have gone. Do not "fix" this to `readMeta`; that puts a full
+        // read of every session back on the startup path.
+        if (sessionId === opts.activeSessionId) {
+            result.kept++;
+            continue;
+        }
+        const tooOld = ref.mtimeMs < cutoff;
+        const beyondCap = index >= retention;
+        if (!tooOld && !beyondCap) {
+            result.kept++;
+            continue;
+        }
+        try {
+            unlinkSync(ref.file);
+            result.removed.push({ ...ref, sessionId });
+            result.bytesFreed += ref.size;
+        }
+        catch {
+            result.failed++;
+            result.kept++;
+        }
+    }
+    sweepOrphanedJobLogs();
+    return result;
+}
+/**
+ * Drop retained job logs whose owning session has just been pruned.
+ *
+ * DELIBERATELY EMPTY, and reserved rather than forgotten. #172 item 1 will
+ * write background-job output to the `subagents/` subtree `paths.ts` reserves
+ * under this same project directory, and #257 exists because that issue asked
+ * "whether the retained-on-disk log is pruned with the session or independently"
+ * and found no answer. The answer is HERE, and it is: with the session, keyed on
+ * the session.
+ *
+ * That makes a job log content owned by its session in exactly the way a
+ * checkpoint's shadow objects are content owned by its manifest — so this is
+ * `CheckpointService.prune`'s second phase, the mark-and-sweep that runs after
+ * the doomed manifests are gone. Filling it in needs one thing the writer does
+ * not have yet: a job log has to record which session owns it, in its path or
+ * its first line.
+ *
+ * The hook is here so item 1 fills it rather than inventing a parallel
+ * retention policy alongside this one. Whatever lands must not `rm -r` this
+ * directory and must not assume every entry is a session's — `subagents/` is a
+ * sibling of the session files, not one of them.
+ *
+ * It takes nothing today because it does nothing; item 1 will want the `cwd`
+ * and the {@link PruneResult} whose `removed` names the sessions whose logs are
+ * now orphaned.
+ */
+function sweepOrphanedJobLogs() {
+    // #172 item 1.
+}

package/dist/session/resume.js

@@ -152,6 +152,11 @@ export function resolveSessionId(cwd, id) {
         throw usageError(`no session \`${id}\` in this project`, [
             "run `cruxy --resume` to pick from recent sessions",
             "sessions are per-directory; check you are in the right one",
+            // #257: retention can now delete a session the user still remembers the
+            // id of, and a pruned session must not read as a bug. The checkpoint
+            // equivalent (`errors/constructors.ts`, CRUXY_E_CHECKPOINT_NOT_FOUND)
+            // says the same thing for the same reason.
+            "old sessions are pruned by retention — adjust `sessions.retention` / `sessions.maxAgeDays` in config to keep more",
         ]);
     }
     return summary;