@cruxy/cli 1.11.1 → 1.11.3

package/dist/session/index.js

@@ -7,17 +7,21 @@
  *    cruxy's fields never make an older one discard a session;
  *  - `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;
+ *  - `recorded-runs.ts` — an ended session's verification record, for
+ *    `cruxy pr` (P2 verification);
  *  - `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+.
  */
 export { PROJECTS_DIR_NAME, RESERVED_SUBDIRS, SESSION_FILE_EXT, projectDir, projectKey, projectsDir, reservedDir, sessionFile, } from "./paths.js";
-export { SessionLog } from "./log.js";
+export { SessionLog, } from "./log.js";
+export { claimSession, describeHolder, ownerFile, readOwner, releaseSession, removeOwnerFile, sessionHeldBy, } from "./owner.js";
 export { defaultExportName, exportMarkdown, } from "./export.js";
 export { foldEvents, readEvents, readMeta, replaySession } from "./replay.js";
+export { latestRecordedRuns, recordedRuns } from "./recorded-runs.js";
 export { redactMessages } from "./redact.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";
+export { cwdMismatchWarning, describeCompactions, describeSession, loadResume, priorDirectoriesWarning, relativeAge, resolveSessionId, resumeById, resumePicker, shortId, PICKER_LIMIT, } from "./resume.js";
+export { KNOWN_EVENT_KINDS, SESSION_FILE_VERSION, emptyCompactionTally, ExternalChangeEventSchema, InstructionLossEventSchema, ResumedEventSchema, SessionEventSchema, SessionMetaSchema, VerificationEventSchema, } from "./types.js";

package/dist/session/log.js

@@ -3,7 +3,9 @@ import path from "node:path";
 import { APP_VERSION } from "../constants.js";
 import { formatBytes } from "../utils/disk.js";
 import { sessionFile } from "./paths.js";
+import { claimSession, describeHolder, releaseSession, sessionHeldBy, } from "./owner.js";
 import { pruneSessions } from "./prune.js";
+import { MAX_FAILURE_NAMES } from "../verification/types.js";
 import { SESSION_FILE_VERSION, } from "./types.js";
 /**
  * How many pruned sessions is worth telling the user about unprompted.
@@ -20,6 +22,8 @@ export class SessionLog {
     currentRunId;
     /** Set once a write fails: the log goes inert rather than warning per turn. */
     broken = false;
+    /** Whether this process has stamped itself as the file's owner (P1). */
+    claimed = 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
@@ -77,6 +81,14 @@ export class SessionLog {
         const log = new SessionLog(file, opts);
         log.pruneOnce(opts);
         if (hasContent(file)) {
+            // OWNERSHIP (P1). A reopen is the moment a second process would start
+            // interleaving its turns into this file, so the stamp is taken here,
+            // eagerly, like the `resumed` event below. `loadResume` has already
+            // refused a file another live cruxy holds; this is the claim that makes
+            // the NEXT resume see us. A fresh session claims at its first flush
+            // instead — see {@link write} — for the same reason `meta` is buffered:
+            // a conversation with nothing in it should leave nothing on disk.
+            log.claim();
             log.write({
                 kind: "resumed",
                 at: new Date().toISOString(),
@@ -113,14 +125,44 @@ export class SessionLog {
             messages,
         });
     }
-    /** An older prefix of `replaced` messages was folded into `summary`. */
-    compaction(replaced, summary) {
+    /**
+     * An older prefix of `replaced` messages was folded into `summary`. `cost`
+     * (P3 context quality) is what the compaction cost — the estimates either
+     * side of it and the summarize call's reported usage; the usage halves are
+     * omitted, not zeroed, when the provider reported nothing.
+     */
+    compaction(replaced, summary, cost) {
         this.write({
             kind: "compaction",
             at: new Date().toISOString(),
             ...this.runId(),
             replaced,
             summary,
+            ...(cost
+                ? {
+                    estimatedBefore: cost.estimatedBefore,
+                    estimatedAfter: cost.estimatedAfter,
+                    ...(cost.summaryInputTokens !== undefined
+                        ? { summaryInputTokens: cost.summaryInputTokens }
+                        : {}),
+                    ...(cost.summaryOutputTokens !== undefined
+                        ? { summaryOutputTokens: cost.summaryOutputTokens }
+                        : {}),
+                }
+                : {}),
+        });
+    }
+    /**
+     * A compaction after which the user's instructions could not all be found
+     * in the synopsis (P3 context quality) — the heuristic's finding, recorded
+     * so it can be audited after the fact. Bounded by the detector, not here.
+     */
+    instructionLoss(sentences) {
+        this.write({
+            kind: "instruction-loss",
+            at: new Date().toISOString(),
+            ...this.runId(),
+            sentences,
         });
     }
     /** `/clear` — history dropped, session kept. */
@@ -135,6 +177,30 @@ export class SessionLog {
     mode(mode) {
         this.write({ kind: "mode", at: new Date().toISOString(), mode });
     }
+    /**
+     * The user approved a plan (plan-durability): the decision kind and the
+     * steps as approved. A fact about the session, dated — see the schema for
+     * why it is recorded and why a resume never acts on it.
+     */
+    planApproved(decision, steps) {
+        this.write({
+            kind: "plan-approved",
+            at: new Date().toISOString(),
+            ...this.runId(),
+            decision,
+            steps: steps.map((s) => ({ id: s.id, title: s.title, kind: s.kind })),
+        });
+    }
+    /** One step of the approved plan changed status (plan-durability). */
+    planStep(stepId, status) {
+        this.write({
+            kind: "plan-step",
+            at: new Date().toISOString(),
+            ...this.runId(),
+            stepId,
+            status,
+        });
+    }
     /**
      * One turn's token usage. Copied here rather than referenced, because the
      * usage store keeps only its newest 50 runs while a session keeps its own
@@ -171,6 +237,46 @@ export class SessionLog {
             count,
         });
     }
+    /**
+     * One observation (P2 verification): a run that actually executed, or a
+     * write refused because its target moved. Written as its own event kind so
+     * the fold treats the two apart, and stamped with the turn's run id like
+     * every other per-turn event, so "what ran in the turn `cruxy rollback <id>`
+     * would undo" is one join, not a guess.
+     *
+     * The failure NAMES are bounded and the output is not copied: the `append`
+     * event already holds the tool_result the model saw. This is an index over
+     * what happened.
+     */
+    observe(obs) {
+        const at = new Date().toISOString();
+        if (obs.kind === "verification") {
+            this.write({
+                kind: "verification",
+                at,
+                ...this.runId(),
+                tool: obs.tool,
+                command: obs.command,
+                ...(obs.source !== undefined ? { source: obs.source } : {}),
+                passed: obs.passed,
+                exitCode: obs.exitCode,
+                durationMs: obs.durationMs,
+                ...(obs.total !== undefined ? { total: obs.total } : {}),
+                failureCount: obs.failureCount,
+                failureNames: obs.failureNames.slice(0, MAX_FAILURE_NAMES),
+                outputTruncated: obs.outputTruncated,
+                substrate: obs.substrate,
+            });
+            return;
+        }
+        this.write({
+            kind: "external-change",
+            at,
+            ...this.runId(),
+            path: obs.path,
+            what: obs.what,
+        });
+    }
     /**
      * Enforce retention for this project, once, as this session opens.
      *
@@ -232,9 +338,46 @@ export class SessionLog {
             this.pendingMeta = null;
             if (!this.writeLine(meta))
                 return false;
+            this.claim(); // the file now exists — so can a second `--resume` of it
         }
         return this.writeLine(event);
     }
+    /**
+     * Stamp this process as the file's owner (P1 — see `owner.ts`). Idempotent.
+     * The stamp is released on process exit; a crash leaves it behind, and that
+     * is fine — a stamp is pid + start-time, so the next reader sees a dead
+     * owner and ignores it. Never fatal: an unwritable stamp is the pre-P1
+     * behaviour (no ownership), and a session must still run without one.
+     */
+    claim() {
+        if (this.claimed)
+            return;
+        // Never overwrite a LIVE owner's stamp. `loadResume` refuses that file
+        // before we get here, so this is the guard for any other writer that
+        // opens a log — and for the race two resumes in the same instant would
+        // be. Recording continues (the format tolerates it); ownership does not
+        // move, so the third process to come along still sees the real holder.
+        const holder = sessionHeldBy(this.file);
+        if (holder) {
+            this.logger?.warn(`session is open in another cruxy (${describeHolder(holder)}) — this process is not taking it over`);
+            return;
+        }
+        this.claimed = claimSession(this.file);
+        if (this.claimed)
+            releaseOnExit(this.file);
+    }
+    /**
+     * Give the file up: remove our stamp. The exit hook does this for the
+     * normal case; this is for a caller that ends a session while the process
+     * lives on (tests, and any future in-process session switch).
+     */
+    close() {
+        if (!this.claimed)
+            return;
+        this.claimed = false;
+        releaseSession(this.file);
+        claimedFiles.delete(this.file);
+    }
     /**
      * 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)
@@ -255,6 +398,24 @@ export class SessionLog {
         }
     }
 }
+/**
+ * Every session file this process has stamped, released together on exit.
+ * ONE listener for the process rather than one per log: a test opens dozens
+ * of logs, and `process.on` warns past ten listeners.
+ */
+const claimedFiles = new Set();
+let exitHookInstalled = false;
+function releaseOnExit(file) {
+    claimedFiles.add(file);
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on("exit", () => {
+        for (const f of claimedFiles)
+            releaseSession(f);
+        claimedFiles.clear();
+    });
+}
 /**
  * Whether `file` is an existing log with content — i.e. this is a reopen.
  *

package/dist/session/owner.js

@@ -0,0 +1,123 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { describeOwner, selfStamp, } from "../utils/process-owner.js";
+import { SESSION_FILE_EXT } from "./paths.js";
+/**
+ * Session ownership across processes (P1).
+ *
+ * A session log is one append-only file, and `SessionLog` was built so that
+ * concurrent appenders interleave whole lines rather than tearing them. That
+ * keeps the file PARSEABLE under two writers; it does not keep it MEANINGFUL.
+ * Two processes that `--resume` the same id each replay the same history,
+ * each append their own turns, and the result is one transcript with two
+ * conversations shuffled into it — replayable, and wrong.
+ *
+ * The fix is ownership, and the minimum that prevents the observed failure is
+ * a stamp, not a lock:
+ *
+ * - `<id>.owner.json` beside the log holds the {@link ProcessStamp} of the
+ *   cruxy that has it open. It is written when the session first lands on
+ *   disk (a new session) or on reopen (a resume), and removed on exit.
+ * - `--resume` reads it BEFORE replaying. A stamp whose process is still
+ *   running is a refusal; a stamp whose process is gone — or whose pid has
+ *   been recycled onto something else — is ignored and overwritten.
+ *
+ * WHY A STAMP AND NOT A LOCK. A lock file that must be deleted to be released
+ * outlives every crash, and a lock that outlives a crash is worse than no
+ * lock: the next `--resume` is refused with nothing to refuse it for, and the
+ * user learns to `rm` it — at which point it stops meaning anything. A pid +
+ * start-time stamp is self-invalidating: liveness is decided by asking the OS,
+ * never by whether cleanup ran. See `utils/process-owner.ts` for why the pid
+ * marker refused for JOB logs is category-correct for sessions.
+ *
+ * WHY NOT A PROJECT-LEVEL LOCK. Several cruxy processes in one project is the
+ * multi-agent case, not a misuse of it. What must not happen is two of them
+ * on ONE session; the stamp is scoped to exactly that.
+ */
+const OwnerSchema = z.object({
+    pid: z.number().int().positive(),
+    token: z.string().min(1),
+    startedAt: z.string(),
+    /** When the stamp was written — for messages. */
+    claimedAt: z.string(),
+});
+/** `<id>.owner.json` next to `<id>.jsonl`. */
+export function ownerFile(sessionFile) {
+    const dir = path.dirname(sessionFile);
+    const id = path.basename(sessionFile, SESSION_FILE_EXT);
+    return path.join(dir, `${id}.owner.json`);
+}
+/** The recorded owner, or null when there is none (absent, unreadable, malformed). */
+export function readOwner(sessionFile) {
+    let raw;
+    try {
+        raw = readFileSync(ownerFile(sessionFile), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = OwnerSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Who has the session open right now, if anyone other than this process.
+ * A stale stamp is not a holder; neither is our own.
+ */
+export function sessionHeldBy(sessionFile) {
+    const owner = readOwner(sessionFile);
+    if (!owner)
+        return null;
+    return describeOwner(owner) === "live" ? owner : null;
+}
+/**
+ * Record this process as the session's owner. Temp-then-rename so a reader
+ * never sees a half-written stamp; `0600` like everything else in `~/.cruxy`.
+ * Never throws: a stamp that cannot be written degrades to the pre-P1
+ * behaviour (no ownership), and the session must still run.
+ */
+export function claimSession(sessionFile) {
+    const file = ownerFile(sessionFile);
+    const me = selfStamp();
+    const record = { ...me, claimedAt: new Date().toISOString() };
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+        renameSync(tmp, file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove our stamp — only ours; a later owner's is left alone. Never throws. */
+export function releaseSession(sessionFile) {
+    const owner = readOwner(sessionFile);
+    if (!owner || describeOwner(owner) !== "self")
+        return;
+    try {
+        unlinkSync(ownerFile(sessionFile));
+    }
+    catch {
+        // already gone, or unwritable — nothing to do either way
+    }
+}
+/** Drop a session's stamp unconditionally — for deleting the session itself. */
+export function removeOwnerFile(sessionFile) {
+    try {
+        unlinkSync(ownerFile(sessionFile));
+    }
+    catch {
+        // no stamp to remove
+    }
+}
+/** One line for a refusal or a picker row: which process, since when. */
+export function describeHolder(stamp) {
+    return `pid ${stamp.pid}, started ${stamp.startedAt}`;
+}

package/dist/session/prune.js

@@ -4,6 +4,7 @@ import { INTERRUPTED, idKey, jobLogFilesByRecency, readJobLogTerminal, sessionKe
 import { SESSION_RETENTION_FLOOR, } from "../config/index.js";
 import { sessionFilesByRecency } from "./list.js";
 import { SESSION_FILE_EXT } from "./paths.js";
+import { removeOwnerFile, sessionHeldBy } from "./owner.js";
 /** `<sessionId>.jsonl` → `<sessionId>`. */
 function idOf(file) {
     return path.basename(file, SESSION_FILE_EXT);
@@ -59,6 +60,15 @@ export function pruneSessions(cwd, opts) {
             result.kept++;
             continue;
         }
+        // A session ANOTHER live cruxy has open is spared for the same reason our
+        // own is (P1): its writer would recreate the file on its next append with
+        // no `meta` line, and that session would be unloadable from then on. The
+        // stamp is pid + start-time, so a crashed owner's file is prunable again
+        // the moment it is looked at — nothing outlives the crash.
+        if (sessionHeldBy(ref.file)) {
+            result.kept++;
+            continue;
+        }
         const tooOld = ref.mtimeMs < cutoff;
         const beyondCap = index >= retention;
         if (!tooOld && !beyondCap) {
@@ -67,6 +77,7 @@ export function pruneSessions(cwd, opts) {
         }
         try {
             unlinkSync(ref.file);
+            removeOwnerFile(ref.file); // a stale stamp has nothing left to own
             result.removed.push({ ...ref, sessionId });
             result.bytesFreed += ref.size;
         }

package/dist/session/recorded-runs.js

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { sessionFilesByRecency } from "./list.js";
+import { readEvents, readMeta } from "./replay.js";
+/**
+ * The verification record of a session that has ENDED, read back from its log
+ * (P2 verification). `cruxy pr` runs outside any session, so there is no
+ * ledger in the process; the log is the durable side of the same record, and
+ * the runs it holds are the evidence there is for a PR opened from here.
+ *
+ * Every `verification` event is returned, in the order it was written — the
+ * fold in `replay.ts` keeps only the LAST run (what `/status` shows after a
+ * resume); a PR body lists them all. Nothing is filtered by content or age:
+ * each run carries its timestamp, and the reader judges whether a run from
+ * before the last edit still counts.
+ */
+export function recordedRuns(file) {
+    const runs = [];
+    for (const event of readEvents(file).events) {
+        if (event.kind !== "verification")
+            continue;
+        runs.push({
+            at: event.at,
+            tool: event.tool,
+            command: event.command,
+            ...(event.source !== undefined ? { source: event.source } : {}),
+            passed: event.passed,
+            exitCode: event.exitCode,
+            durationMs: event.durationMs,
+            ...(event.total !== undefined ? { total: event.total } : {}),
+            failureCount: event.failureCount,
+            failureNames: event.failureNames,
+            outputTruncated: event.outputTruncated,
+            substrate: event.substrate,
+        });
+    }
+    return runs;
+}
+/**
+ * The NEWEST session for `cwd` and the runs it recorded, or null when the
+ * project has no session whose meta names this directory (`projectKey` can
+ * collide — `a-b` and `a/b` — so meta.cwd is compared, as resume does).
+ *
+ * The newest session, not the newest session that ran something: if the last
+ * thing done here recorded no runs, the honest answer is no section, not the
+ * runs of an older session cherry-picked because it has some.
+ */
+export function latestRecordedRuns(cwd) {
+    const here = path.resolve(cwd);
+    for (const ref of sessionFilesByRecency(cwd)) {
+        const meta = readMeta(ref.file);
+        if (!meta || path.resolve(meta.cwd) !== here)
+            continue;
+        return { sessionId: meta.sessionId, runs: recordedRuns(ref.file) };
+    }
+    return null;
+}

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 { KNOWN_EVENT_KINDS, SessionEventSchema, SessionMetaSchema, } from "./types.js";
+import { KNOWN_EVENT_KINDS, SessionEventSchema, SessionMetaSchema, emptyCompactionTally, } from "./types.js";
 /**
  * Replay: fold an append-only event log back into the state a session needs to
  * resume (P2).
@@ -109,6 +109,10 @@ export function foldEvents(events, counts = {}) {
     let planMode = false;
     let mode = null;
     let redactions = 0;
+    let lastVerification;
+    let externalChanges = 0;
+    let plan;
+    const compactions = emptyCompactionTally();
     const resumes = [];
     const usage = { input_tokens: 0, output_tokens: 0 };
     for (const event of events) {
@@ -123,6 +127,22 @@ export function foldEvents(events, counts = {}) {
                     ...asMessages(event.summary),
                     ...messages.slice(event.replaced),
                 ];
+                // And tallied (P3): the count is the events; the sums cover only the
+                // events that carry a cost, so a pre-P3 compaction counts as one that
+                // happened and not as one that freed nothing.
+                compactions.count++;
+                if (event.estimatedBefore !== undefined &&
+                    event.estimatedAfter !== undefined) {
+                    compactions.measured++;
+                    compactions.freedTokens += Math.max(0, event.estimatedBefore - event.estimatedAfter);
+                    compactions.summaryInputTokens += event.summaryInputTokens ?? 0;
+                    compactions.summaryOutputTokens += event.summaryOutputTokens ?? 0;
+                }
+                break;
+            case "instruction-loss":
+                // Counted, not folded: the synopsis is already in the history as the
+                // model sees it. This is the fact that it may be missing something.
+                compactions.instructionLosses++;
                 break;
             case "clear":
                 messages = [];
@@ -156,6 +176,56 @@ export function foldEvents(events, counts = {}) {
                 // could be added without touching `meta` or the message array.
                 resumes.push({ at: event.at, cwd: event.cwd });
                 break;
+            case "verification":
+                // Last-writer-wins, and never folded into the messages: a run is a
+                // fact ABOUT the turn, not a turn in it. The tool_result the model saw
+                // is already in the `append` events; this is the structured claim.
+                lastVerification = {
+                    at: event.at,
+                    tool: event.tool,
+                    command: event.command,
+                    ...(event.source !== undefined ? { source: event.source } : {}),
+                    passed: event.passed,
+                    exitCode: event.exitCode,
+                    durationMs: event.durationMs,
+                    ...(event.total !== undefined ? { total: event.total } : {}),
+                    failureCount: event.failureCount,
+                    failureNames: event.failureNames,
+                    outputTruncated: event.outputTruncated,
+                    substrate: event.substrate,
+                };
+                break;
+            case "external-change":
+                // Counted, not folded: the refusal wrote nothing, so there is nothing
+                // in the history to adjust — only a fact for the resume notice.
+                externalChanges++;
+                break;
+            case "plan-approved":
+                // A new approval replaces the last: every step starts `pending`, as
+                // the executor had it, and the `plan-step` events that follow move
+                // them. Never folded into the messages — the plan's text is already
+                // there as the model's own `submit_plan` call.
+                plan = {
+                    approvedAt: event.at,
+                    decision: event.decision,
+                    steps: event.steps.map((s) => ({
+                        id: s.id,
+                        title: s.title,
+                        kind: s.kind,
+                        status: "pending",
+                    })),
+                };
+                break;
+            case "plan-step": {
+                // A transition for a step the last approval did not name is skipped,
+                // not an error: a torn `plan-approved` line, or a newer build's
+                // vocabulary. Position matters — a step left `running` is one whose
+                // outcome the log never received.
+                const step = plan?.steps.find((s) => s.id === event.stepId);
+                if (step)
+                    step.status = event.status;
+                break;
+            }
             case "meta":
                 break;
         }
@@ -172,6 +242,10 @@ export function foldEvents(events, counts = {}) {
         unknownEvents: counts.unknownEvents ?? 0,
         resumes,
         redactions,
+        ...(lastVerification ? { lastVerification } : {}),
+        externalChanges,
+        compactions,
+        ...(plan ? { plan } : {}),
     };
 }
 /** Read and parse a session file into its events, counting unusable lines. */