@cruxy/cli 1.7.1 → 1.8.1

package/dist/cli/session-commands.js

@@ -3,6 +3,7 @@ import { existsSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { COMMAND_CATALOG } from "./command-catalog.js";
 import { contextReport } from "../agent/context.js";
+import { permissionsReport, revokedLine } from "../agent/permissions.js";
 import { buildSessionStatus } from "../agent/status.js";
 import { resolveCheckpointDiff } from "../checkpoint/diff.js";
 import { rollbackLatestRun } from "../checkpoint/run-rollback.js";
@@ -11,6 +12,7 @@ import { resolveSlash } from "../hooks/index.js";
 import { contextReportLines } from "../render/context-view.js";
 import { compactTokens } from "../render/units.js";
 import { renderUnifiedDiff } from "../render/index.js";
+import { permissionsReportLines } from "../render/permissions-view.js";
 import { sessionStatusLines } from "../render/status-view.js";
 import { defaultExportName, exportMarkdown } from "../session/index.js";
 import { readDiskCapacitySync } from "../utils/disk.js";
@@ -104,6 +106,10 @@ export async function dispatchCommand(input, ctx) {
         handleStatus(ctx);
         return { kind: "handled" };
     }
+    if (trimmed === "/permissions" || trimmed.startsWith("/permissions ")) {
+        handlePermissions(trimmed, ctx);
+        return { kind: "handled" };
+    }
     if (trimmed === "/diff" || trimmed.startsWith("/diff ")) {
         await handleDiff(trimmed, ctx);
         return { kind: "handled" };
@@ -337,6 +343,59 @@ function handleStatus(ctx) {
         out.print(out.fit(line));
     }
 }
+/**
+ * `/permissions` (cli#196) — what this session may do without asking, and the
+ * one way to take a standing grant back.
+ *
+ * REVOKE IS THE ARGUMENT FORM, not a selectable row. Views take no input: the
+ * TUI's key lease belongs to overlays, and a permissions screen that grabbed it
+ * to offer a cursor would be a drawer wearing a view's clothes. The argument
+ * form is also the one a user can script, a test can drive, and a REPL without
+ * a picker can still reach — `/permissions revoke 2` means the same thing in
+ * every shell.
+ *
+ * The number is the row number the list just printed. A `Scope` has no stable
+ * id to name instead, and inventing one would put a token on screen that exists
+ * for no other purpose; the user is pointing at a visible row, so the row's
+ * position is the honest handle. It is re-read from `list()` at the moment of
+ * the revoke, so a grant recorded since the last print shifts nothing — the
+ * order is append-only and a revoke only ever removes.
+ */
+function handlePermissions(input, ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const arg = input.slice("/permissions".length).trim();
+    if (arg !== "") {
+        const match = /^revoke\s+(\S+)$/.exec(arg);
+        if (!match) {
+            out.print(t.muted("usage: /permissions [revoke <n>]"));
+            return;
+        }
+        const allowlist = session.allowlist;
+        if (!allowlist) {
+            // Not "nothing to revoke": a session with no allowlist wired has no grant
+            // surface at all, and saying which is more useful than a failed lookup.
+            out.print(t.muted("this session does not track grants"));
+            return;
+        }
+        // Parsed strictly — `Number("2x")` is NaN but `parseInt("2x")` is 2, and a
+        // typo must never resolve to a row the user did not mean to drop.
+        const n = /^\d+$/.test(match[1]) ? Number(match[1]) : NaN;
+        const grant = Number.isNaN(n) ? null : allowlist.revoke(n - 1);
+        if (!grant) {
+            const count = allowlist.size();
+            out.print(t.muted(count === 0
+                ? "no standing grants to revoke"
+                : `no grant ${match[1]} — /permissions lists 1${count === 1 ? "" : `-${count}`}`));
+            return;
+        }
+        out.print(t.muted(revokedLine(grant)));
+        return;
+    }
+    for (const line of permissionsReportLines(permissionsReport(session), t)) {
+        out.print(out.fit(line));
+    }
+}
 /**
  * `/diff` (P6 track 4) — what has changed on disk, without leaving the session.
  *

package/dist/cli/session-factory.js

@@ -522,6 +522,10 @@ opts = {}) {
         onRunUsage,
         budget: sessionBudget,
         jobs: jobManager,
+        // The SAME allowlist the plan policy and the interactive policy share, so
+        // `/permissions` lists the grants this session's prompts actually spend —
+        // not a second list that agrees with them only by luck.
+        allowlist,
         recorder: opts.recorder,
         restore: opts.restore,
     });

package/dist/indexing/walker.js

@@ -1,8 +1,13 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { globToRegexBody, isBinary } from "./util.js";
-/** Directories never descended into, regardless of ignore files. */
-const ALWAYS_IGNORE_DIRS = new Set([".git", "node_modules", ".cruxy"]);
+/**
+ * Directories never descended into, regardless of ignore files. Exported because
+ * `checkpoint/coverage.ts` pairs each name with the reason a checkpoint cannot
+ * restore what is under it — a name added here without a reason there fails the
+ * build, so the walker cannot quietly widen what the ceiling still calls safe.
+ */
+export const ALWAYS_IGNORE_DIRS = new Set([".git", "node_modules", ".cruxy"]);
 const DEFAULT_IGNORE_FILES = [".gitignore", ".cruxyignore"];
 /**
  * Hard denylist for secret-bearing files. Applied independently of ignore files

package/dist/limits/index.js

@@ -8,4 +8,4 @@
  * rendering lives in `tui/limits-panel.ts` — nothing here formats anything.
  */
 export { LimitsCache } from "./cache.js";
-export { reduceLimits, bindingWindow, usedFraction } from "./reduce.js";
+export { reduceLimits, bindingWindow, scarcestWindow, usedFraction, } from "./reduce.js";

package/dist/limits/reduce.js

@@ -144,15 +144,26 @@ export function reduceLimits(res, readAt = Date.now()) {
         readAt,
     };
 }
+/**
+ * TWO SELECTORS, TWO QUESTIONS. {@link bindingWindow} answers *which window will
+ * stop you first*; {@link scarcestWindow} answers *how much may you actually
+ * spend right now*. They are not the same question and they do not always pick
+ * the same window, so merging them would make one of the two answers wrong —
+ * see each function for which.
+ */
 /**
  * The window that will stop this user FIRST — the one the gate itself calls
  * binding: whichever of monthly/burst has the smaller REMAINING fraction
  * (`internal/budget/decide.go`).
  *
- * This is what earns the single bar the rail has room for. Drawing the month
- * because it is the bigger number would routinely show a comfortable 6% while
- * the trailing-12h window — a quarter of the month's cap on every self-serve
- * tier — is the one about to refuse the next request.
+ * FOR DISPLAY. This is what earns the single bar the rail has room for. Drawing
+ * the month because it is the bigger number would routinely show a comfortable
+ * 6% while the trailing-12h window — a quarter of the month's cap on every
+ * self-serve tier — is the one about to refuse the next request.
+ *
+ * The fraction is right HERE because a bar is a fraction: the pixels state
+ * proportion, so the window drawn must be the one whose proportion is the
+ * warning. It is wrong for admission, and {@link scarcestWindow} says why.
  */
 export function bindingWindow(monthly, burst) {
     if (!monthly)
@@ -164,6 +175,37 @@ export function bindingWindow(monthly, burst) {
         ? { window: burst, name: "burst" }
         : { window: monthly, name: "month" };
 }
+/**
+ * The window with the least ABSOLUTE remaining — the ceiling an admission check
+ * must respect (cli#212).
+ *
+ * FOR ADMISSION. BOTH windows gate every request, so a draw of D is admitted
+ * only when `D ≤ monthly.remaining` AND `D ≤ burst.remaining` — which makes the
+ * spendable allowance exactly `min(remaining)`, a number of tokens rather than
+ * a proportion.
+ *
+ * WHY {@link bindingWindow} CANNOT SERVE HERE, concretely: a Core user 5% into
+ * the month (700k of 14M left) whose burst is at 14% (500k of 3.5M left). The
+ * fraction rule names the month, correctly — 5% is the figure worth showing.
+ * But handing 700k to an admission check authorises a batch the burst will
+ * refuse at 500k, and it refuses it AFTER the tokens are spent, against a
+ * sliding window that refills only by trickle over twelve hours. The two rules
+ * disagree exactly when the caps differ by 4×, which is to say on every
+ * self-serve tier, in the ordinary case rather than a corner one.
+ *
+ * The error is one-directional, which is why it is worth two functions: erring
+ * toward the smaller remainder narrows a fan-out that might have fitted, and
+ * erring toward the larger one spends a window that cannot be un-spent.
+ */
+export function scarcestWindow(monthly, burst) {
+    if (!monthly)
+        return burst ? { window: burst, name: "burst" } : undefined;
+    if (!burst)
+        return { window: monthly, name: "month" };
+    return burst.remaining < monthly.remaining
+        ? { window: burst, name: "burst" }
+        : { window: monthly, name: "month" };
+}
 /** The fraction of a cap consumed, clamped to [0,1] for display. */
 export function usedFraction(w) {
     if (!usableCap(w.cap))

package/dist/mcp/bounds.js

@@ -1,3 +1,4 @@
+import { MAX_SCHEMA_DEPTH, schemaDepth } from "../tools/schema-depth.js";
 const PERMISSIVE_SCHEMA = {
     type: "object",
     additionalProperties: true,
@@ -5,9 +6,16 @@ const PERMISSIVE_SCHEMA = {
 /**
  * Apply the bounds to a raw `tools/list`. Over the count cap → keep the first N
  * (by advertised order) and report `droppedCount`. Per tool: an over-long
- * description is truncated with a marker; an over-size input schema is replaced
- * with a permissive `object` schema and a note (we never forward an unbounded
- * schema, but we also never claim the args are constrained when we dropped it).
+ * description is truncated with a marker; an over-size OR over-deep input schema
+ * is replaced with a permissive `object` schema and a note (we never forward an
+ * unbounded or unsendable schema, but we also never claim the args are
+ * constrained when we dropped it).
+ *
+ * Degrading beats dying, and it is the same trade the byte cap already makes: an
+ * over-deep tool stays callable with unconstrained args and a visible note,
+ * rather than taking the session down with it. Nothing is lost locally by the
+ * swap — the adapter delegates arg validation to the server either way
+ * (`PASSTHROUGH`), and the approval gate is untouched.
  */
 export function boundToolList(tools, bounds) {
     const kept = tools.slice(0, bounds.maxTools);
@@ -30,6 +38,16 @@ export function boundToolList(tools, bounds) {
             inputSchema = { ...PERMISSIVE_SCHEMA };
             notes.push(`input schema (${schemaBytes} bytes) exceeded the ${bounds.maxSchemaBytes}-byte cap and was replaced with a permissive one`);
         }
+        // ORDER MATTERS: depth is measured on the POST-byte-cap value. A schema the
+        // byte cap already replaced is permissive (depth 1) and passes trivially, so
+        // the only schema this counter ever walks is one that fit `maxSchemaBytes` —
+        // which is what bounds the walk. Measuring the raw schema first would hand a
+        // hostile server an unbounded one.
+        const depth = schemaDepth(inputSchema);
+        if (depth >= MAX_SCHEMA_DEPTH) {
+            inputSchema = { ...PERMISSIVE_SCHEMA };
+            notes.push(`input schema nests ${depth} levels deep, at or over the ${MAX_SCHEMA_DEPTH}-level provider limit, and was replaced with a permissive one`);
+        }
         return { name: t.name, description, inputSchema, notes };
     });
     return { tools: bounded, droppedCount };

package/dist/plan/policy.js

@@ -5,11 +5,23 @@
  * for the rest of the run, recording the real scope in the shared
  * {@link SessionAllowlist} so U.3's own scoping (`scopeCovers`) governs reuse.
  *
- * What it deliberately does NOT do — the two-tier boundary:
+ * What it deliberately does NOT do — the boundary, in three parts:
  *   • **destructive** actions always fall through to the base policy (prompt);
  *   • **ungrantable** actions (`scope:"none"`) always fall through (prompt),
  *     even if the tier is `mutate` — because `SessionAllowlist.grant` is a no-op
- *     on `none`, an ungrantable action can never be pre-approved.
+ *     on `none`, an ungrantable action can never be pre-approved;
+ *   • **irreversible** actions always fall through (prompt), even if the tier is
+ *     `mutate` AND the scope is grantable (cli#193). This is the only one of the
+ *     three that `tier` cannot express: a write to `/etc/passwd` is tier
+ *     `mutate` with a perfectly good exact-file scope, and the checkpoint still
+ *     cannot restore it. Without this clause, "approve + allow safe steps"
+ *     silently authorized exactly that for the rest of the run.
+ *
+ * That last clause is why it is checked HERE rather than left to the allowlist.
+ * The ceiling in `SessionAllowlist.allows` covers grants being *spent*; this
+ * branch never asks `allows()` — it is pre-consent, so it *writes* a grant. It
+ * is the one path into the allowlist that the chokepoint cannot defend, so it
+ * carries its own copy of the same rule.
  *
  * So approving a plan (even with "allow safe steps") never consents to a
  * destructive or irreversible action; those re-confirm at execution time.
@@ -27,14 +39,18 @@ export class PlanExecutionPolicy {
         this.safeStepGrants = true;
     }
     async decide(request) {
-        // Already covered by a prior session grant (scoped, tier-keyed) → allow.
+        // Already covered by a prior session grant (scoped, tier-keyed, and — since
+        // cli#193 — reversible; `allows` enforces the ceiling itself) → allow.
         if (this.allowlist.allows(request))
             return { allow: true };
-        // The one plan-mode shortcut: a grantable mutate action, pre-consented by
-        // the "allow safe steps" choice. Record its concrete scope, then allow.
+        // The one plan-mode shortcut: a grantable, REVERSIBLE mutate action,
+        // pre-consented by the "allow safe steps" choice. Record its concrete scope,
+        // then allow. `!request.irreversible` is load-bearing, not defensive — see
+        // the third bullet in this class's doc comment.
         if (this.safeStepGrants &&
             request.tier === "mutate" &&
-            request.scope.kind !== "none") {
+            request.scope.kind !== "none" &&
+            !request.irreversible) {
             this.allowlist.grant(request);
             return { allow: true };
         }

package/dist/render/permissions-view.js

@@ -0,0 +1,88 @@
+import { fit, reflow, visibleWidth } from "./layout.js";
+/**
+ * The ceiling, in one line.
+ *
+ * Stated as an ABSOLUTE, because since cli#193 it is one: `allows()` checks
+ * `irreversible` before it matches any scope, so there is no longer a "unless
+ * you granted it" clause to add. #196 asked this screen to be honest about the
+ * asymmetry; the honest version today is that the asymmetry is closed, and the
+ * cost — a granted `git` not covering `git commit` — is what the inert marks
+ * and the re-prompt copy explain.
+ */
+const CEILING = "irreversible actions always ask — in every mode, and no session grant outranks it";
+/**
+ * How wide the label column may grow. A grant label is usually short (`git
+ * commands`, `changes under src/`), but an exact-file grant or a test grant
+ * carries a path or a whole command, and one long row must not cost every other
+ * row its tier and root.
+ */
+const LABEL_MAX_COLS = 34;
+/** `key  value`, on the same gutter `/status` uses so the two screens align. */
+function row(key, value, t) {
+    return `  ${t.muted(key.padEnd(11))} ${value}`;
+}
+/** `2 standing · 1 inert`, or what an empty/unwired list has to say instead. */
+function grantSummary(grants, t) {
+    if (!grants)
+        return t.muted("not tracked in this session");
+    if (grants.length === 0) {
+        return t.muted("none — every action has been decided one at a time");
+    }
+    const dead = grants.filter((g) => g.dead).length;
+    const live = grants.length - dead;
+    const head = `${live} standing`;
+    return dead === 0
+        ? head
+        : `${head} ${t.warning(`${t.glyph.sep} ${dead} inert`)}`;
+}
+/** The full `/permissions` block as lines to print. */
+export function permissionsReportLines(report, t, width = Infinity) {
+    const lines = [t.heading("permissions")];
+    lines.push(row("mode", `${t.strong(report.mode)} ${t.muted(`— ${report.modeDescription}`)}`, t));
+    // The ceiling is the one row that is the same in every session, and it is here
+    // for exactly that reason: a screen listing what runs without asking has to
+    // state what asks anyway, next to it, or the list reads as the whole answer.
+    lines.push(row("ceiling", report.autoApproves ? t.warning(CEILING) : t.muted(CEILING), t));
+    lines.push(row("grants", grantSummary(report.grants, t), t));
+    if (report.grants && report.grants.length > 0) {
+        lines.push("");
+        // One label column, sized to the longest label the list actually holds and
+        // capped so a pathological grant (a long exact path, a long test command)
+        // cannot push the tier and the root off a normal terminal. Padded on the
+        // VISIBLE width, because a coloured label carries escape bytes that
+        // `padEnd` would count and the terminal would not.
+        const labelCols = Math.min(LABEL_MAX_COLS, Math.max(...report.grants.map((g) => visibleWidth(g.label))));
+        for (const g of report.grants) {
+            const n = t.muted(`${g.n}`.padStart(2));
+            const text = fit(g.label, labelCols, t.glyph.ellipsis);
+            const pad = " ".repeat(Math.max(0, labelCols - visibleWidth(text)));
+            const label = g.dead ? t.muted(text) : t.strong(text);
+            lines.push(`  ${n}  ${label}${pad}  ${t.muted(`${g.tier} ${t.glyph.sep} ${g.where}`)}`);
+            if (!g.dead)
+                continue;
+            // Why it can never match, on its own rows so the reason survives a narrow
+            // terminal intact — an inert grant the user cannot read the reason for is
+            // the same puzzle as an unmarked one.
+            const indent = "      ";
+            const room = Number.isFinite(width)
+                ? Math.max(20, width - indent.length)
+                : Infinity;
+            const reason = `inert — ${g.dead}`;
+            const wrapped = Number.isFinite(room) ? reflow(reason, room) : [reason];
+            for (const line of wrapped)
+                lines.push(`${indent}${t.warning(line)}`);
+        }
+    }
+    lines.push("");
+    // THE SCOPE OF THE SCREEN. Every background job builds its own
+    // ApprovalService with its own allowlist, so a job's grants are neither
+    // listed here nor revoked by anything typed here. A permissions screen that
+    // implied otherwise would be understating what the session can still do.
+    lines.push(t.muted("this is the foreground session only — each background job keeps its own grants"));
+    if (report.grants && report.grants.length > 0) {
+        lines.push(t.muted("/permissions revoke <n> drops one — actions already decided keep their decision"));
+    }
+    return Number.isFinite(width)
+        ? lines.map((l) => fit(l, width, t.glyph.ellipsis))
+        : lines;
+}

package/dist/render/state.js

@@ -43,9 +43,28 @@ export function describePhase(phase, glyph = UNICODE_GLYPHS) {
             const base = t && t.input + t.output > 0
                 ? `thinking${e} ${glyph.sep} tokens ${glyph.caretUp}${formatTokens(t.input)} ${glyph.caretDown}${formatTokens(t.output)}`
                 : `thinking${e}`;
-            // The real routing tier (C.30), appended honestly when present — same
-            // ` · ` joiner as the token counts.
-            return phase.tier ? `${base} ${glyph.sep} ${phase.tier}` : base;
+            // The real routing tier (C.30) and the effort the gateway says it applied,
+            // appended honestly when present — same ` · ` joiner as the token counts.
+            //
+            // Order matters under truncation. `fitStatusLine`'s last resort clips the
+            // TAIL, so what is appended last is shed first: effort goes before the
+            // tier, which goes before the token counts, which go before "thinking…".
+            // That is the intended priority — the tier answers "what ran", effort only
+            // refines it.
+            //
+            // Effort is labelled rather than shown bare. `kavi · none` beside a tier
+            // name reads as a second tier; `kavi · effort none` cannot. The label
+            // costs seven columns and buys the line's only defence against being
+            // misread, which is worth more here than seven columns are.
+            const parts = [base];
+            if (phase.tier)
+                parts.push(phase.tier);
+            // A present `none` is the gateway SAYING no reasoning ran — a real answer
+            // to "what actually ran", and the one this readout exists to make
+            // visible. Absent stays absent; see ServedRouting.reasoningEffort.
+            if (phase.effort)
+                parts.push(`effort ${phase.effort}`);
+            return parts.join(` ${glyph.sep} `);
         }
         case "calling-tool":
             return `${phase.label}${e}`;

package/dist/session/index.js

@@ -16,6 +16,6 @@ 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, listSessions, summarizeSession, } from "./list.js";
-export { cwdMismatchWarning, describeSession, loadResume, relativeAge, resumeById, resumePicker, shortId, PICKER_LIMIT, } from "./resume.js";
-export { SESSION_FILE_VERSION, SessionEventSchema, SessionMetaSchema, } from "./types.js";
+export { findSession, isAmbiguous, listSessionRefs, listSessions, matchSessionRefs, summarizeSession, } from "./list.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

@@ -1,6 +1,7 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { projectDir, SESSION_FILE_EXT } from "./paths.js";
+import { readMeta } from "./replay.js";
 import { MessageSchema, SessionEventSchema, SessionMetaSchema, } from "./types.js";
 /**
  * Listing sessions for the resume picker and the TUI sidebar (P2). Both read
@@ -22,10 +23,18 @@ function toTitle(text) {
  * Summarize one session file: its meta, its first user prompt (the title) and
  * how many user turns it holds.
  *
- * This reads the whole file, which is the honest cost of counting turns. It is
- * bounded in practice — the picker asks for ten — and a session file is text
- * measured in tens of kilobytes. If it ever stops being cheap the fix is a
- * sidecar index, not a partial read that reports a wrong count.
+ * This reads the whole file, which is the honest cost of counting turns — a
+ * partial read cannot produce a correct count, and reporting a wrong one is
+ * worse than paying for a right one.
+ *
+ * What changed: this used to claim the cost was "bounded in practice — the
+ * 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
+ * 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.
  */
 export function summarizeSession(file) {
     let raw;
@@ -89,10 +98,18 @@ export function summarizeSession(file) {
     return { ...meta, title: title ?? UNTITLED, turns };
 }
 /**
- * Every session recorded for `cwd`'s project, most-recently-updated first.
- * Missing directory → empty list (not an error: no sessions yet is normal).
+ * Session files in `cwd`'s project, most-recently-modified first.
+ *
+ * `readdir` plus one `stat` each — NO file is opened. This is the ordering step
+ * that lets every caller below bound its own work: recency is knowable from the
+ * directory alone, so the expensive per-file read only ever has to happen for
+ * the files a caller is actually going to show.
+ *
+ * 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.
  */
-export function listSessions(cwd, limit = Infinity) {
+function sessionRefsByRecency(cwd) {
     const dir = projectDir(cwd);
     let names;
     try {
@@ -101,37 +118,106 @@ export function listSessions(cwd, limit = Infinity) {
     catch {
         return [];
     }
-    const summaries = [];
+    const files = [];
     for (const name of names) {
         if (!name.endsWith(SESSION_FILE_EXT))
             continue;
-        const summary = summarizeSession(path.join(dir, name));
+        const file = path.join(dir, name);
+        try {
+            files.push({ file, mtimeMs: statSync(file).mtimeMs });
+        }
+        catch {
+            continue; // deleted mid-listing
+        }
+    }
+    // Newest first, with the path as a tiebreak so two files written in the same
+    // millisecond list in a stable order rather than whatever `readdir` returned.
+    files.sort((a, b) => b.mtimeMs - a.mtimeMs || a.file.localeCompare(b.file));
+    return files;
+}
+/**
+ * Every session recorded for `cwd`'s project, most-recently-updated first,
+ * 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
+ * `limit` valid summaries exist, so the picker asking for ten reads ten files
+ * and not two hundred.
+ *
+ * OVER-FETCH AND REFILL is why this is a loop and not a `slice`. A file with no
+ * readable meta summarizes to `null` and is skipped — that tolerance is the
+ * point of the format and `tree.test.ts` pins it. Taking the ten most recent
+ * files and summarizing those would let one junk file among them silently
+ * return nine rows; walking until ten SUMMARIES exist costs one wasted parse
+ * per junk file and always returns ten when ten are there.
+ */
+export function listSessions(cwd, limit = Infinity) {
+    const summaries = [];
+    for (const { file } of sessionRefsByRecency(cwd)) {
+        if (summaries.length >= limit)
+            break;
+        const summary = summarizeSession(file);
         if (summary)
             summaries.push(summary);
     }
-    summaries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
-    return Number.isFinite(limit) ? summaries.slice(0, limit) : summaries;
+    return summaries;
+}
+/**
+ * Every session's IDENTITY for `cwd`'s project, most-recently-updated first.
+ *
+ * One meta line per file, via {@link readMeta} — no turn counting, no title.
+ * This is the index `--resume <id>` resolves against, and it exists because
+ * resolution never needed the expensive half: on a 200-session project it costs
+ * ~10ms against ~120ms for the equivalent {@link listSessions}, and the resume
+ * path used to build the expensive one two or three times over.
+ *
+ * `meta` stays authoritative for the id, deliberately — the FILENAME also
+ * carries it, and matching on that would be cheaper still, but it would make a
+ * file with no readable meta resolvable and then unloadable. A session that
+ * cannot be summarized must not be offerable either.
+ */
+export function listSessionRefs(cwd) {
+    const refs = [];
+    for (const { file, mtimeMs } of sessionRefsByRecency(cwd)) {
+        const meta = readMeta(file);
+        if (meta)
+            refs.push({ sessionId: meta.sessionId, file, mtimeMs });
+    }
+    return refs;
+}
+/**
+ * Match an id (or id prefix) against an already-built index.
+ *
+ * Pure, and separate from the reading, so ONE index can answer both "is this
+ * ambiguous?" and "which one is it?" — the two questions the resume path asks
+ * back to back, and used to rebuild the whole listing to answer separately.
+ *
+ * An exact id always wins outright: `abc` names the session called `abc` even
+ * when `abcdef` also exists, so a full id is never ambiguous against something
+ * that merely starts the same way.
+ */
+export function matchSessionRefs(refs, id) {
+    const exact = refs.find((r) => r.sessionId === id);
+    if (exact)
+        return [exact];
+    return refs.filter((r) => r.sessionId.startsWith(id));
 }
 /**
  * Find one session by id (or unambiguous id prefix) within `cwd`'s project.
- * Returns null when nothing matches; throws nothing — the caller decides how
- * loudly to fail.
+ * Returns null when nothing matches or the prefix is ambiguous; throws nothing
+ * — the caller decides how loudly to fail.
  *
  * Prefix matching exists because the ids are UUIDs and nobody is going to type
  * one; the picker and the sidebar both show a short form.
+ *
+ * Builds its own index. `resolveSessionId` in `resume.ts` is the path that
+ * builds ONE and asks both questions of it; prefer that when you need both.
  */
 export function findSession(cwd, id) {
-    const all = listSessions(cwd);
-    const exact = all.find((s) => s.sessionId === id);
-    if (exact)
-        return exact;
-    const matches = all.filter((s) => s.sessionId.startsWith(id));
-    return matches.length === 1 ? matches[0] : null;
+    const matches = matchSessionRefs(listSessionRefs(cwd), id);
+    return matches.length === 1 ? summarizeSession(matches[0].file) : null;
 }
 /** Whether an id prefix matches more than one session (an ambiguous resume). */
 export function isAmbiguous(cwd, id) {
-    const all = listSessions(cwd);
-    if (all.some((s) => s.sessionId === id))
-        return false;
-    return all.filter((s) => s.sessionId.startsWith(id)).length > 1;
+    return matchSessionRefs(listSessionRefs(cwd), id).length > 1;
 }

package/dist/session/log.js

@@ -15,23 +15,42 @@ export class SessionLog {
         this.currentRunId = opts.currentRunId;
     }
     /**
-     * Open (or create) a session log. A NEW file gets its `meta` line; reopening
-     * an existing one (a `--resume`) does not — `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 already
-     * takes the first `meta`, so a duplicate could only ever mislead a later
-     * reader, never help one.
+     * Open (or create) a session log.
+     *
+     * 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.
+     *
+     * 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
+     * session begun in one directory and continued in another recorded nothing
+     * about the second, so `cwdMismatchWarning` told the user at the time and the
+     * 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 never returns null: a write problem on an
-     * existing file surfaces on the first append, which warns and goes inert.
+     * 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.
      */
     static open(opts) {
         const file = opts.file ?? sessionFile(opts.cwd, opts.sessionId);
         const log = new SessionLog(file, opts);
-        if (hasContent(file))
+        if (hasContent(file)) {
+            log.write({
+                kind: "resumed",
+                at: new Date().toISOString(),
+                cwd: opts.cwd,
+                roots: opts.roots ?? [],
+                cliVersion: APP_VERSION,
+            });
             return log;
+        }
         const ok = log.write({
             kind: "meta",
             version: SESSION_FILE_VERSION,