@cruxy/cli 1.8.0 → 1.8.1

package/dist/cli/commands/run.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { LimitsClient } from "@cruxy/sdk";
 import { LimitsCache } from "../../limits/index.js";
 import { logger } from "../../utils/logger.js";
-import { SessionLog, listSessions, resumeById, resumePicker, shortId, } from "../../session/index.js";
+import { SessionLog, listSessions, loadResume, resolveSessionId, resumePicker, shortId, } from "../../session/index.js";
 /** Sessions shown in the TUI sidebar — the same depth as the resume picker. */
 const SIDEBAR_SESSIONS = 10;
 import { globalDir, loadConfig, resolveApiKey } from "../../config/index.js";
@@ -56,6 +56,56 @@ export async function executeRun(promptParts, opts) {
     const t = themeForColor(shouldUseColor(process.stdout));
     const invokedAs = opts.commandName ?? "cruxy run";
     const interactive = prompt === "";
+    // ORDER OF COMPLAINTS (#172 item 3). Three things can refuse this run before
+    // it starts, and they are checked most-specific first:
+    //
+    //   1. a bad `--root`            (the workspace cannot even be built)
+    //   2. a bad `--resume <id>`     (the session named does not exist)
+    //   3. no prompt, and no TTY     (nothing to do, no way to be asked)
+    //
+    // The terminal check USED to come first, which meant
+    // `cruxy --resume no-such-id < /dev/null` was told to add a message — advice
+    // that, followed, only surfaces the real error one run later. `program.ts`
+    // deliberately routes `--resume` past the guidance banner so a bad id fails
+    // loud; the guard sitting in front of it undid exactly that.
+    //
+    // The tradeoff this reordering accepts: `--root` errors now precede the
+    // terminal message too, because id validation needs `primaryRoot` and so the
+    // workspace has to be built first. That is the right way round — a
+    // non-existent root is a more specific complaint than "needs a terminal", and
+    // it was already the first thing to fail on every OTHER path.
+    //
+    // The guard is NOT simply moved below resume resolution instead. That would
+    // put `loadConfig` and the missing-key check in front of it, so a keyless
+    // non-TTY run would be told to authenticate rather than that it has nothing
+    // to do — trading one misleading diagnostic for another.
+    // Declared workspace roots (C.26). This is the ONE place `run` reads the
+    // process working directory — the invocation directory is the base for
+    // resolving `--root` paths and the sole root when none are declared. Every
+    // subsystem below derives its cwd from the WORKSPACE (`primaryRoot`), never
+    // re-reads the invocation directory, so nothing can silently split-brain to
+    // a different dir than the roots the tools see (the guard test pins this).
+    const invocationCwd = process.cwd();
+    // No --root → a trivial single-root workspace (byte-identical to pre-C.26).
+    // --root builds a genuine multi-root Workspace and fails fast HERE — a
+    // missing / non-dir / overlapping root (CRUXY_E_ROOT_OVERLAP) throws before
+    // onboarding or the session starts, never a half-built session.
+    const workspace = opts.root.length
+        ? await buildWorkspace(opts.root, { cwd: invocationCwd })
+        : sessionWorkspace(invocationCwd);
+    const primaryRoot = workspace.primary().absPath;
+    // VALIDATION ONLY — deliberately not the load. `resolveSessionId` answers
+    // "does this id name a session?" from one meta line per file; the replay that
+    // actually restores the conversation happens far below, once we know the run
+    // is going to proceed. A valid `--resume <id> < /dev/null` with no message is
+    // still going to be turned away by the guard just below, and it should not
+    // have paid for a full `replaySession` to get there.
+    //
+    // Bare `--resume` (no id) cannot be validated here and is not: the picker
+    // needs a terminal, so it stays below the guard where it has always been.
+    const resumeTarget = typeof opts.resume === "string" && opts.resume !== ""
+        ? resolveSessionId(primaryRoot, opts.resume)
+        : null;
     // No prompt and stdin isn't a terminal: there's no way to read input and
     // nothing to do — fail fast instead of hanging on a line that never comes.
     //
@@ -78,21 +128,6 @@ export async function executeRun(promptParts, opts) {
     const loaded = loadConfig();
     const { config, sources } = loaded;
     let apiKey = resolveApiKey(config.model.provider);
-    // Declared workspace roots (C.26). This is the ONE place `run` reads the
-    // process working directory — the invocation directory is the base for
-    // resolving `--root` paths and the sole root when none are declared. Every
-    // subsystem below derives its cwd from the WORKSPACE (`primaryRoot`), never
-    // re-reads the invocation directory, so nothing can silently split-brain to
-    // a different dir than the roots the tools see (the guard test pins this).
-    const invocationCwd = process.cwd();
-    // No --root → a trivial single-root workspace (byte-identical to pre-C.26).
-    // --root builds a genuine multi-root Workspace and fails fast HERE — a
-    // missing / non-dir / overlapping root (CRUXY_E_ROOT_OVERLAP) throws before
-    // onboarding or the session starts, never a half-built session.
-    const workspace = opts.root.length
-        ? await buildWorkspace(opts.root, { cwd: invocationCwd })
-        : sessionWorkspace(invocationCwd);
-    const primaryRoot = workspace.primary().absPath;
     logger.info(t.muted(`model:   ${config.model.provider}/${config.model.model}`));
     logger.info(t.muted(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
     // Multi-root honesty (JC-6/C.26): reads fan every root. With per-root
@@ -147,10 +182,12 @@ export async function executeRun(promptParts, opts) {
     // a repo moved would be worse than saying so plainly.
     let resumed = null;
     if (opts.resume !== undefined && opts.resume !== false) {
-        resumed =
-            typeof opts.resume === "string" && opts.resume !== ""
-                ? resumeById(primaryRoot, opts.resume)
-                : await resumePicker(primaryRoot, { logger });
+        // `resumeTarget` is the id already validated above the guard; loading it is
+        // all that is left. Bare `--resume` resolves here, where the TTY it needs is
+        // guaranteed — the guard above turned away every run that lacked one.
+        resumed = resumeTarget
+            ? loadResume(resumeTarget, primaryRoot)
+            : await resumePicker(primaryRoot, { logger });
         if (resumed) {
             for (const warning of resumed.warnings)
                 logger.warn(warning);

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,

package/dist/session/replay.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { modeFromFlags } from "../agent/mode.js";
 import { redactMessages } from "./redact.js";
-import { SessionEventSchema, SessionMetaSchema, } from "./types.js";
+import { KNOWN_EVENT_KINDS, SessionEventSchema, SessionMetaSchema, } from "./types.js";
 /**
  * Replay: fold an append-only event log back into the state a session needs to
  * resume (P2).
@@ -11,8 +11,7 @@ import { SessionEventSchema, SessionMetaSchema, } from "./types.js";
  * the array the model last saw, including the synthetic compaction summaries.
  * Nothing is re-derived or re-summarised on the way back in.
  *
- * TOLERANCE IS THE POINT. A line that will not parse is SKIPPED and counted,
- * never fatal:
+ * TOLERANCE IS THE POINT. A line that will not parse is SKIPPED, never fatal:
  *  - a torn final line from a crash mid-append would otherwise cost the whole
  *    conversation (this is the failure temp-then-rename buys off at write time;
  *    an append-only log buys it off here instead);
@@ -20,8 +19,25 @@ import { SessionEventSchema, SessionMetaSchema, } from "./types.js";
  *    heard of is skipped rather than rejected, which together with the
  *    `.passthrough()` schemas is what keeps two CLI versions able to share one
  *    home directory.
- * `SessionState.skipped` carries the count so a caller can say so out loud
- * rather than presenting a partial history as complete.
+ *
+ * THE TWO ARE COUNTED APART (#172 item 2), because they are not the same fact
+ * and the caller says something different about each. A damaged line means
+ * content was LOST — "the restored history may be incomplete" is warranted. An
+ * unknown kind means content is not visible HERE while the file is perfectly
+ * intact.
+ *
+ * Conflating them was survivable only while unknown kinds were rare. The
+ * `resumed` event is written on EVERY reopen, so an older build sharing a home
+ * directory would have announced possible history loss on every single resume —
+ * a forward-compatibility mechanism producing a corruption warning as routine
+ * output. `SessionState.skipped` now counts only damage;
+ * `SessionState.unknownEvents` counts the rest.
+ *
+ * This fixes readers from this build forward. An ALREADY-SHIPPED cruxy has the
+ * old reader and will still say "unreadable lines" when it meets a `resumed`
+ * event; nothing here can reach it. That is the cost of the split landing with
+ * the event rather than before it, and it is bounded — it misreports, it does
+ * not lose anything.
  */
 /**
  * The one cast in this module, isolated and explained.
@@ -36,20 +52,37 @@ import { SessionEventSchema, SessionMetaSchema, } from "./types.js";
 function asMessages(validated) {
     return validated;
 }
-/** Parse one line, or `null` when it is unusable (torn, or an unknown kind). */
+/**
+ * Classify one line.
+ *
+ * The distinction that matters is inside the failure case. A line that is valid
+ * JSON, is an object, and names a `kind` this build has never heard of is a
+ * NEWER cruxy's event — the file is intact and the forward-compatibility rule is
+ * working as designed. Anything else that fails is damage.
+ *
+ * A known kind with a payload that does not validate counts as DAMAGE, not as
+ * unknown: this build understands that kind, so failing to parse it means the
+ * line is wrong rather than merely new.
+ */
 function parseLine(line) {
     const trimmed = line.trim();
     if (trimmed === "")
-        return null;
+        return { outcome: "blank" };
     let raw;
     try {
         raw = JSON.parse(trimmed);
     }
     catch {
-        return null;
+        return { outcome: "damaged" }; // torn mid-write
     }
     const parsed = SessionEventSchema.safeParse(raw);
-    return parsed.success ? parsed.data : null;
+    if (parsed.success)
+        return { outcome: "event", event: parsed.data };
+    const kind = raw?.kind;
+    if (typeof kind === "string" && !KNOWN_EVENT_KINDS.has(kind)) {
+        return { outcome: "unknown" };
+    }
+    return { outcome: "damaged" };
 }
 /**
  * Fold events into {@link SessionState}. Exported separately from file reading
@@ -60,7 +93,7 @@ function parseLine(line) {
  * which directory the history refers to, and resuming a conversation whose
  * origin is unknown is precisely what ruling 4 forbids.
  */
-export function foldEvents(events, skipped = 0) {
+export function foldEvents(events, counts = {}) {
     const metaEvent = events.find((e) => e.kind === "meta");
     if (!metaEvent) {
         throw new Error("session log has no readable meta line");
@@ -76,6 +109,7 @@ export function foldEvents(events, skipped = 0) {
     let planMode = false;
     let mode = null;
     let redactions = 0;
+    const resumes = [];
     const usage = { input_tokens: 0, output_tokens: 0 };
     for (const event of events) {
         switch (event.kind) {
@@ -116,6 +150,12 @@ export function foldEvents(events, skipped = 0) {
                 messages = redactMessages(messages).messages;
                 redactions++;
                 break;
+            case "resumed":
+                // Recorded, never folded into anything the model sees. A reopen is a
+                // fact ABOUT the conversation, not a turn in it — the whole reason it
+                // could be added without touching `meta` or the message array.
+                resumes.push({ at: event.at, cwd: event.cwd });
+                break;
             case "meta":
                 break;
         }
@@ -128,7 +168,9 @@ export function foldEvents(events, skipped = 0) {
         // Auto-approve reads false there, which is right: it was not a thing that
         // could be on, so nothing is being inferred.
         mode: mode ?? modeFromFlags(planMode, false),
-        skipped,
+        skipped: counts.skipped ?? 0,
+        unknownEvents: counts.unknownEvents ?? 0,
+        resumes,
         redactions,
     };
 }
@@ -137,21 +179,29 @@ export function readEvents(file) {
     const raw = readFileSync(file, "utf8");
     const events = [];
     let skipped = 0;
+    let unknownEvents = 0;
     for (const line of raw.split("\n")) {
-        if (line.trim() === "")
-            continue;
-        const event = parseLine(line);
-        if (event)
-            events.push(event);
-        else
-            skipped++;
+        const parsed = parseLine(line);
+        switch (parsed.outcome) {
+            case "event":
+                events.push(parsed.event);
+                break;
+            case "unknown":
+                unknownEvents++;
+                break;
+            case "damaged":
+                skipped++;
+                break;
+            case "blank":
+                break;
+        }
     }
-    return { events, skipped };
+    return { events, skipped, unknownEvents };
 }
 /** Read a session file and fold it into resumable state. */
 export function replaySession(file) {
-    const { events, skipped } = readEvents(file);
-    return foldEvents(events, skipped);
+    const { events, skipped, unknownEvents } = readEvents(file);
+    return foldEvents(events, { skipped, unknownEvents });
 }
 /**
  * Read ONLY the meta line — enough to list a session without folding its whole

package/dist/session/resume.js

@@ -1,6 +1,6 @@
 import { selectList } from "../components/index.js";
 import { usageError } from "../errors/index.js";
-import { findSession, isAmbiguous, listSessions } from "./list.js";
+import { listSessionRefs, listSessions, matchSessionRefs, summarizeSession, } from "./list.js";
 import { replaySession } from "./replay.js";
 /** How many sessions the bare-`--resume` picker offers. */
 export const PICKER_LIMIT = 10;
@@ -47,6 +47,28 @@ export function cwdMismatchWarning(state, cwd) {
     return (`this session was recorded in ${state.meta.cwd}, but you are in ${cwd} — ` +
         `its history refers to files and paths from the original directory`);
 }
+/**
+ * Directories this session has run in BEFORE, other than the one we are
+ * resuming into now (#172 item 2). Returns a warning to print, or null.
+ *
+ * Distinct from {@link cwdMismatchWarning}, which compares where the
+ * conversation BEGAN against where it is being resumed. This compares where it
+ * has since RUN. The two disagree in exactly the case that motivated the
+ * `resumed` event: begin in `/a`, resume in `/b`, then resume in `/a` again —
+ * `meta.cwd` matches, so the mismatch check is silent, and yet the history now
+ * contains a whole stretch of work done against a different tree.
+ *
+ * Nothing could say this before, because nothing recorded it. Sessions written
+ * before the event simply have no `resumes` and are silent here — absence is
+ * "not recorded", never "did not happen".
+ */
+export function priorDirectoriesWarning(state, cwd) {
+    const others = [...new Set(state.resumes.map((r) => r.cwd))].filter((dir) => dir !== cwd && dir !== state.meta.cwd);
+    if (others.length === 0)
+        return null;
+    return (`this session has also run in ${others.join(", ")} — ` +
+        `part of its history refers to files and paths from ${others.length === 1 ? "that directory" : "those directories"}`);
+}
 /**
  * Load one session and collect its warnings. Throws a usage error when the
  * file cannot be replayed at all (no meta line) — an unreadable session is
@@ -67,10 +89,23 @@ export function loadResume(session, cwd) {
     const mismatch = cwdMismatchWarning(state, cwd);
     if (mismatch)
         warnings.push(mismatch);
+    const elsewhere = priorDirectoriesWarning(state, cwd);
+    if (elsewhere)
+        warnings.push(elsewhere);
     if (state.skipped > 0) {
         warnings.push(`${state.skipped} unreadable line${state.skipped === 1 ? "" : "s"} in the session log were skipped — ` +
             `the restored history may be incomplete`);
     }
+    if (state.unknownEvents > 0) {
+        // Deliberately NOT the sentence above. The file is intact; this build is
+        // simply older than whatever wrote those lines, and saying "unreadable"
+        // about a healthy log would send the user looking for damage that is not
+        // there. What IS true is that some of what the session recorded cannot be
+        // shown here.
+        warnings.push(`${state.unknownEvents} event${state.unknownEvents === 1 ? "" : "s"} in this session ` +
+            `${state.unknownEvents === 1 ? "was" : "were"} written by a newer cruxy and ${state.unknownEvents === 1 ? "is" : "are"} not shown — ` +
+            `the conversation itself is complete; upgrade to see the rest`);
+    }
     if (state.redactions > 0) {
         // Said on resume because the alternative is a user finding `[redacted …]`
         // in a transcript and not knowing whether cruxy did it or the model wrote
@@ -82,27 +117,54 @@ export function loadResume(session, cwd) {
     return { session, state, warnings };
 }
 /**
- * Resolve `--resume <id>`. Fails loud on an unknown or ambiguous id rather than
- * silently starting a new session — the user named something specific.
+ * VALIDATE `--resume <id>` — which session does this name? — without loading it.
+ *
+ * Split from the loading half for two reasons, one of them ordering:
+ *
+ *  1. `executeRun` has to answer "is this a real id?" BEFORE the non-TTY guard,
+ *     so `cruxy --resume no-such-id < /dev/null` complains about the id rather
+ *     than about the terminal. It must not have to pay a full `replaySession`
+ *     to find that out — a VALID id in that same position is still going to be
+ *     told it needs a terminal, and reading a whole conversation only to throw
+ *     it away is exactly the cost this split avoids.
+ *  2. Both questions — ambiguous? which one? — are now asked of ONE index. This
+ *     used to build the full listing up to three times (`isAmbiguous`, then
+ *     `findSession`, then a third time to name the collisions), each one a
+ *     complete read and parse of every session file in the project.
+ *
+ * Fails loud on an unknown or ambiguous id rather than silently starting a new
+ * session — the user named something specific.
+ *
+ * The one file that matched IS summarized, so the caller still gets the title
+ * and turn count the resume line prints. That is one read, not N.
  */
-export function resumeById(cwd, id) {
-    if (isAmbiguous(cwd, id)) {
-        const matches = listSessions(cwd)
-            .filter((s) => s.sessionId.startsWith(id))
-            .map((s) => shortId(s.sessionId));
+export function resolveSessionId(cwd, id) {
+    const matches = matchSessionRefs(listSessionRefs(cwd), id);
+    if (matches.length > 1) {
+        const names = matches.map((m) => shortId(m.sessionId)).join(", ");
         throw usageError(`\`${id}\` matches more than one session`, [
-            `did you mean one of: ${matches.join(", ")}?`,
+            `did you mean one of: ${names}?`,
             "run `cruxy --resume` to pick from a list",
         ]);
     }
-    const found = findSession(cwd, id);
-    if (!found) {
+    const summary = matches.length === 1 ? summarizeSession(matches[0].file) : null;
+    if (!summary) {
         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",
         ]);
     }
-    return loadResume(found, cwd);
+    return summary;
+}
+/**
+ * Resolve `--resume <id>` all the way to restorable state: validate, then load.
+ *
+ * `executeRun` calls the two halves separately, so validation can precede the
+ * non-TTY guard; this composition is what everything else (and the tests) use
+ * where there is no ordering constraint to respect.
+ */
+export function resumeById(cwd, id) {
+    return loadResume(resolveSessionId(cwd, id), cwd);
 }
 /**
  * Bare `--resume`: pick from the most recent sessions, or start a new one.

package/dist/session/types.js

@@ -248,6 +248,41 @@ export const RedactEventSchema = z
     count: z.number().int().nonnegative().default(0),
 })
     .passthrough();
+/**
+ * A session was REOPENED (#172 item 2) — `--resume` found this log and
+ * continued it.
+ *
+ * `meta` is written once and never again, on purpose: it records where and when
+ * the conversation BEGAN, and a second copy written from wherever it was
+ * resumed would make "the session's directory" ambiguous. That ruling stands.
+ * Its consequence was that a resume left no trace at all — a session started in
+ * one directory and continued in another looked, from the file, as though it
+ * had only ever run in the first.
+ *
+ * This event closes that without touching `meta`'s authority. `meta.cwd` is
+ * still where the conversation began; `resumed.cwd` is somewhere it has since
+ * run. A reader can tell the two apart because they are different kinds.
+ *
+ * SCOPE, stated because the obvious next step is deliberately NOT taken here:
+ * this makes a cross-directory resume AUDITABLE, not DISCOVERABLE. The file
+ * still lives under `projectKey(meta.cwd)`, and `listSessions` for the other
+ * directory does one `readdir` of its own project dir and will never see it.
+ * Surfacing it there needs a pointer written into the second directory, or a
+ * scan across every project — a separate decision with a real cost, not a
+ * side effect of recording the fact.
+ */
+export const ResumedEventSchema = z
+    .object({
+    kind: z.literal("resumed"),
+    at: z.string(),
+    /** The primary root the session was resumed INTO. */
+    cwd: z.string(),
+    /** Roots declared on the resuming run — multi-root can differ per run. */
+    roots: z.array(RootRefSchema).default([]),
+    /** The build that reopened it; a session can outlive several. */
+    cliVersion: z.string().optional(),
+})
+    .passthrough();
 /** Every event, discriminated on `kind`. */
 export const SessionEventSchema = z.discriminatedUnion("kind", [
     SessionMetaSchema,
@@ -258,4 +293,14 @@ export const SessionEventSchema = z.discriminatedUnion("kind", [
     SessionModeEventSchema,
     UsageEventSchema,
     RedactEventSchema,
+    ResumedEventSchema,
 ]);
+/**
+ * Every `kind` this build understands, derived from the union itself so the two
+ * cannot drift.
+ *
+ * This exists so the reader can tell "a line I do not understand" from "a line
+ * that is damaged" — see `replay.ts`. Those are different facts about a file and
+ * they used to be counted as one.
+ */
+export const KNOWN_EVENT_KINDS = new Set(SessionEventSchema.options.map((option) => option.shape.kind.value));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {