@cruxy/cli 1.2.1 → 1.4.0

package/dist/agent/context.js

@@ -0,0 +1,178 @@
+import { COMPACTION_MARKER } from "./prompts.js";
+/** Characters a single content block contributes to the estimate. */
+function blockChars(block) {
+    switch (block.type) {
+        case "text":
+            return block.text.length;
+        case "tool_use":
+            return block.name.length + JSON.stringify(block.input).length;
+        case "tool_result":
+            return block.content.length;
+    }
+}
+/** Characters one message contributes. Block structure and role labels are ignored. */
+export function messageChars(message) {
+    if (typeof message.content === "string")
+        return message.content.length;
+    let chars = 0;
+    for (const block of message.content)
+        chars += blockChars(block);
+    return chars;
+}
+/** Chars → tokens, the one place the chars/4 heuristic is applied. */
+export function charsToTokens(chars) {
+    return Math.ceil(chars / 4);
+}
+/**
+ * Estimate the token footprint of a message list with a cheap chars/4 heuristic
+ * — no tokenizer dependency. Good enough to decide *when* to compact; exact
+ * counts are deferred to a later phase. Counts only textual payload (block
+ * structure and role labels are negligible and ignored).
+ */
+export function estimateTokens(messages) {
+    let chars = 0;
+    for (const message of messages)
+        chars += messageChars(message);
+    return charsToTokens(chars);
+}
+/** Compute a reading from a history — pure, and shared by the gauge and `/context`. */
+export function readContext(messages, budget) {
+    // Deliberately the SAME expression `compactIfOverThreshold` branches on: the
+    // reserve covers the system prompt and tool schemas that `estimateTokens`
+    // never sees, and omitting it here would under-report by ~4.5k tokens and let
+    // the panel read "comfortable" while the seam was about to compact.
+    const used = estimateTokens(messages) + budget.reserveTokens;
+    const total = budget.maxTokens;
+    return {
+        used,
+        total,
+        fraction: total <= 0 ? 1 : Math.min(1, Math.max(0, used / total)),
+        compactAt: Math.round(budget.compactThreshold * total),
+    };
+}
+/**
+ * Choose the boundary between the summarized prefix and the kept-recent tail.
+ *
+ * Tool-call integrity is the constraint: a `tool_use` (assistant) and its
+ * matching `tool_result` (the next user message) must never straddle the cut,
+ * or the next provider call breaks. A real user *prompt* (`role:"user"` with
+ * string content) only occurs at a completed turn boundary, where every prior
+ * tool exchange is already resolved — so the kept region must begin there. The
+ * synthetic compaction-summary user message is also string content, so a repeat
+ * compaction always finds at least the previous summary as a clean cut.
+ *
+ * Start from `length - keepRecentMessages` and walk *backwards* to the nearest
+ * such prompt: this keeps at least the recent floor and lands clean. Returns
+ * the cut index, or `null` if no safe boundary leaves a non-empty prefix (e.g.
+ * a single long in-progress turn — nothing safe to compact).
+ *
+ * Extracted from `Session` (P6 track 3) so `/context` can report what compaction
+ * would do by calling the function that decides what it does. A second
+ * implementation for the explanation would be free to be subtly wrong exactly
+ * where it mattered.
+ */
+export function findCut(messages, keepRecentMessages) {
+    const start = messages.length - keepRecentMessages;
+    for (let i = start; i >= 1; i--) {
+        const message = messages[i];
+        if (message.role === "user" && typeof message.content === "string")
+            return i;
+    }
+    return null;
+}
+/** Which part a message belongs to. */
+function classify(message) {
+    if (typeof message.content === "string") {
+        // The synthetic pair a previous compaction spliced in. Worth its own bucket:
+        // "40% of your context is a summary of earlier context" is a different fact
+        // from "40% is your prompts", and it is the one that says compaction has
+        // already run.
+        return message.content.startsWith(COMPACTION_MARKER)
+            ? "summaries"
+            : "prompts";
+    }
+    if (message.role === "user")
+        return "tool results";
+    return message.content.some((b) => b.type === "tool_use")
+        ? "tool calls"
+        : "assistant";
+}
+/** A one-line excerpt of a message, for recognition rather than reading. */
+function excerpt(message, max = 60) {
+    let text;
+    if (typeof message.content === "string") {
+        text = message.content;
+    }
+    else {
+        const first = message.content[0];
+        text =
+            first === undefined
+                ? ""
+                : first.type === "text"
+                    ? first.text
+                    : first.type === "tool_use"
+                        ? first.name
+                        : first.content;
+    }
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * Analyse a history against a budget. Pure; no I/O, no theme, no rendering.
+ *
+ * @param topN how many individual messages to name as the largest contributors.
+ */
+export function contextReport(messages, budget, topN = 5) {
+    const charsByPart = new Map();
+    const contributors = [];
+    for (const [index, message] of messages.entries()) {
+        const chars = messageChars(message);
+        const part = classify(message);
+        const bucket = charsByPart.get(part) ?? { chars: 0, messages: 0 };
+        bucket.chars += chars;
+        bucket.messages += 1;
+        charsByPart.set(part, bucket);
+        contributors.push({ chars, message, index });
+    }
+    const parts = [...charsByPart.entries()]
+        .map(([part, b]) => ({
+        part,
+        tokens: charsToTokens(b.chars),
+        messages: b.messages,
+    }))
+        .filter((p) => p.tokens > 0)
+        .sort((a, b) => b.tokens - a.tokens);
+    const largest = contributors
+        .filter((c) => c.chars > 0)
+        .sort((a, b) => b.chars - a.chars)
+        .slice(0, topN)
+        .map((c) => ({
+        label: classify(c.message),
+        excerpt: excerpt(c.message),
+        tokens: charsToTokens(c.chars),
+        position: c.index + 1,
+    }));
+    const cut = findCut(messages, budget.keepRecentMessages);
+    const reading = readContext(messages, budget);
+    return {
+        reading,
+        messages: messages.length,
+        reserveTokens: budget.reserveTokens,
+        parts,
+        largest,
+        compaction: {
+            cut,
+            droppedMessages: cut ?? 0,
+            droppedTokens: cut === null ? 0 : estimateTokens(messages.slice(0, cut)),
+            keptMessages: cut === null ? messages.length : messages.length - cut,
+            keptTokens: cut === null
+                ? estimateTokens(messages)
+                : estimateTokens(messages.slice(cut)),
+            // Compared against the UNROUNDED product, exactly as
+            // `compactIfOverThreshold` does — `compactAt` is rounded for display, and
+            // a report claiming to say what compaction would do must not disagree
+            // with the seam over a fraction of a token.
+            overThreshold: reading.used > budget.compactThreshold * budget.maxTokens,
+        },
+    };
+}

package/dist/agent/index.js

@@ -1,3 +1,4 @@
 export * from "./loop.js";
+export * from "./mode.js";
 export * from "./session.js";
 export * from "./prompts.js";

package/dist/agent/loop.js

@@ -24,6 +24,11 @@ export async function runAgent(args) {
     // gateway does not offer throws CRUXY_E_ROUTING_TIER_UNAVAILABLE here — so a
     // misrouted run never reaches provider.stream (no request sent with the wrong
     // tier), and never silently falls back to a different one.
+    //
+    // Resolving per RUN, not per iteration, is still right after P6 track 1 made
+    // the choice mutable: a `/model` mid-turn is impossible (the input loop has
+    // released stdin and is awaiting `session.send`), and a run that changed model
+    // between its own iterations would attribute one history to two tiers.
     const routed = args.router
         ? resolveTaskModel(args.router, args.taskClass ?? "main-turn")
         : null;
@@ -38,7 +43,11 @@ export async function runAgent(args) {
     }
 }
 /** The body of {@link runAgent}, split out so turn cleanup lives in one finally. */
-async function driveLoop(args, renderer, routed) {
+async function driveLoop(args, renderer, 
+// `tier` is optional because a router may decline and send the request as
+// `auto` — no tier was chosen client-side, so there is none to report until
+// the gateway's routing frame arrives. See `resolveTaskModel`.
+routed) {
     const { provider, registry, config, ctx } = args;
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
@@ -142,6 +151,16 @@ async function driveLoop(args, renderer, routed) {
                 case "routing":
                     servedTier = ev.routing.tier;
                     routingMode = ev.routing.mode;
+                    // Publish to the renderer HERE, not at the `setPhase` above. That one
+                    // fires before `provider.stream` is called, so the served tier is not
+                    // knowable yet and it can only carry `routed?.tier` — what this run
+                    // ASKED for. This frame is the first moment the backend's answer
+                    // exists, and it is the answer worth showing: it resolves `auto`, and
+                    // it reflects a downgrade the client never chose.
+                    renderer?.servedRouting({
+                        tier: ev.routing.tier,
+                        ...(ev.routing.mode !== undefined ? { mode: ev.routing.mode } : {}),
+                    });
                     break;
                 case "text_delta":
                     turnText += ev.text;

package/dist/agent/mode.js

@@ -0,0 +1,103 @@
+/**
+ * Session modes (P5 track 3) — the one piece of state that says how much a turn
+ * does without asking.
+ *
+ * Two facts govern that, and before P5 they were kept in different places and at
+ * different lifetimes: plan mode lived on the `Session` (runtime, journaled,
+ * restored on resume) while auto-approve was a config key read from disk. The
+ * config key was also dead — nothing consumed `agent.autoApprove`, and
+ * `ApprovalConfigSchema` in the same file stated flatly that no auto-approve
+ * mode exists "not behind a footgun flag". One file promised something another
+ * refused to do.
+ *
+ * A mode is the cross product of the two, named. That is what makes it a
+ * SUBSUMPTION rather than a third source of truth: `Session` holds exactly one
+ * mode and derives both booleans from it, so there is no state in which plan
+ * mode and the mode indicator can disagree.
+ *
+ * Auto-approve is deliberately a RUNTIME mode and only that — never a config
+ * key. A flag on disk silently disarms every approval in every session that
+ * loads it, with nothing on screen to say so; a mode is chosen in the session it
+ * affects, shown while it is active, and gone when the session ends.
+ */
+/**
+ * Cycle order, and the order every list of modes uses. Shift+Tab walks this
+ * ring; the last entry wraps to the first.
+ */
+export const SESSION_MODES = [
+    "manual",
+    "auto-approve",
+    "plan",
+    "full-auto",
+];
+/** The default for a session that says nothing — the pre-P5 behaviour exactly. */
+export const DEFAULT_MODE = "manual";
+/** The next mode in the ring. Total: every mode has a successor. */
+export function nextMode(mode) {
+    const i = SESSION_MODES.indexOf(mode);
+    return SESSION_MODES[(i + 1) % SESSION_MODES.length];
+}
+/** Whether this mode proposes a plan before executing (C.31). */
+export function modePlans(mode) {
+    return mode === "plan" || mode === "full-auto";
+}
+/** Whether this mode allows gated actions without prompting. */
+export function modeAutoApproves(mode) {
+    return mode === "auto-approve" || mode === "full-auto";
+}
+/** Short label for the status line and the mode indicator. */
+export const MODE_LABELS = {
+    manual: "manual",
+    "auto-approve": "auto-approve",
+    plan: "plan",
+    "full-auto": "full-auto",
+};
+/**
+ * One line saying what the mode will actually do, shown when it changes.
+ *
+ * A mode that skips approvals has to SAY it skips approvals at the moment it is
+ * switched on. The whole objection to the config flag was that it disarmed the
+ * gate with nothing on screen; a runtime mode that announced itself as vaguely
+ * as "auto-approve on" would reproduce the same problem more slowly.
+ *
+ * These lines must not overstate the mode either. Saying "including destructive
+ * ones" when the ceiling stops exactly those would teach the user to expect a
+ * silence that never comes — and, worse, teach them the gate is gone when it is
+ * not. Each auto line names the suppression AND its limit.
+ */
+export function modeDescription(mode) {
+    switch (mode) {
+        case "manual":
+            return "every action asks first";
+        case "auto-approve":
+            return "reversible actions run WITHOUT asking — irreversible ones still ask";
+        case "plan":
+            return "propose a plan for approval, then ask before each action";
+        case "full-auto":
+            return "propose a plan, then run it WITHOUT asking — irreversible actions still ask";
+    }
+}
+/**
+ * Parse a mode from user input (`/mode <name>`), or null when it names nothing.
+ * Never guesses: a typo must not silently arm auto-approve.
+ */
+export function parseMode(text) {
+    const want = text.trim().toLowerCase();
+    return SESSION_MODES.find((m) => m === want) ?? null;
+}
+/**
+ * Recover a mode from the two booleans an older session journaled.
+ *
+ * Sessions recorded before P5 carry `plan-mode` events and nothing else, so
+ * auto-approve reads false — which is right: it was not a thing that could be
+ * on. This is what lets a pre-P5 session resume into the mode it actually had.
+ */
+export function modeFromFlags(plans, autoApproves) {
+    if (plans && autoApproves)
+        return "full-auto";
+    if (plans)
+        return "plan";
+    if (autoApproves)
+        return "auto-approve";
+    return "manual";
+}

package/dist/agent/prompts.js

@@ -1,5 +1,5 @@
 /**
- * cruxy-code agent prompts.
+ * cruxy agent prompts.
  *
  * These are ORIGINAL prompts written for cruxy — not copied from any other
  * tool. The system prompt is assembled at runtime from a static core plus a

package/dist/agent/session.js

@@ -1,39 +1,19 @@
 import { randomUUID } from "node:crypto";
 import { loadProjectInstructions } from "../config/index.js";
-import { resolveTaskModel } from "../routing/index.js";
+import { resolveTaskModel, } from "../routing/index.js";
 import { UsageCollector, accumulateCacheTokens, } from "../usage/index.js";
 import { Budget } from "./budget.js";
+import { estimateTokens, findCut } from "./context.js";
 import { runAgent, } from "./loop.js";
+import { DEFAULT_MODE, modeAutoApproves, modePlans, nextMode, parseMode, } from "./mode.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
- * Estimate the token footprint of a message list with a cheap chars/4 heuristic
- * — no tokenizer dependency. Good enough to decide *when* to compact; exact
- * counts are deferred to a later phase. Counts only textual payload (block
- * structure and role labels are negligible and ignored).
+ * Re-exported from `agent/context.ts`, where the estimate now lives beside the
+ * cut-point search and the budget reading (P6 track 3) — one module for
+ * everything that measures the window, so the seam that acts on the numbers and
+ * the surfaces that explain them cannot drift.
  */
-export function estimateTokens(messages) {
-    let chars = 0;
-    for (const msg of messages) {
-        if (typeof msg.content === "string") {
-            chars += msg.content.length;
-            continue;
-        }
-        for (const block of msg.content) {
-            switch (block.type) {
-                case "text":
-                    chars += block.text.length;
-                    break;
-                case "tool_use":
-                    chars += block.name.length + JSON.stringify(block.input).length;
-                    break;
-                case "tool_result":
-                    chars += block.content.length;
-                    break;
-            }
-        }
-    }
-    return Math.ceil(chars / 4);
-}
+export { estimateTokens } from "./context.js";
 /**
  * Owns the state of one multi-turn conversation: the running message history and
  * the usage accumulated across turns. Each `send` continues from the prior
@@ -52,43 +32,150 @@ export class Session {
     usage = { input_tokens: 0, output_tokens: 0 };
     /** Stable id for this session (C.22), so a run's usage record groups with the
      * other runs of the same interactive session (`cruxy usage --session`). */
-    sessionId = randomUUID();
+    sessionId;
     /** The most recent run's usage record (C.22) — the one-shot path reads it to
      * print the end-of-run summary. */
     lastRun;
     args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     projectInstructions;
-    /** Mutable so `/plan` can toggle plan mode mid-session. */
-    planMode;
+    /**
+     * The session's mode (P5 track 3) — the ONE piece of state saying how much a
+     * turn does without asking. Mutable so `/mode` and Shift+Tab can change it
+     * mid-session.
+     *
+     * Plan mode is DERIVED from this, not stored beside it. Before P5 the session
+     * held a `planMode` boolean while auto-approve was a (dead) config key, which
+     * is two sources of truth for one question and exactly the shape of bug the
+     * tier work had just finished removing.
+     */
+    mode;
+    /**
+     * How many messages of the CURRENT history the recorder already holds (P2).
+     *
+     * This is what lets an append-only log track an array that is rewritten in
+     * place. The invariant: a replay of the log so far reproduces exactly the
+     * first `recordedCount` messages of the live history. So an append is
+     * `slice(recordedCount)`, and a compaction updates the watermark to the
+     * post-compaction length rather than re-emitting anything.
+     *
+     * It is only ever advanced at points where the history is COHERENT — a
+     * tool_use and its tool_result are never split across a flush — because the
+     * loop calls the compaction seam at the top of an iteration, after the
+     * previous iteration fully resolved its tool calls.
+     */
+    recordedCount = 0;
     constructor(args) {
         this.args = args;
         this.projectInstructions = args.projectInstructions ?? null;
-        // Plan mode requires a wired runner; without one it stays off (no half-on
-        // state where the plan directive is injected but nothing orchestrates it).
-        this.planMode = (args.planMode ?? false) && args.planRunner !== undefined;
+        this.mode = this.resolveMode(args.mode ?? DEFAULT_MODE);
+        // Resume (P2): adopt the replayed state verbatim. The history is already
+        // recorded in the log we are continuing, so the watermark starts at its
+        // full length — otherwise the first flush would append the whole restored
+        // conversation a second time.
+        const restore = args.restore;
+        this.sessionId = restore?.sessionId ?? randomUUID();
+        if (restore) {
+            this.messages = restore.messages;
+            this.usage.input_tokens = restore.usage.input_tokens;
+            this.usage.output_tokens = restore.usage.output_tokens;
+            this.recordedCount = restore.messages.length;
+            this.mode = this.resolveMode(restore.mode);
+        }
+    }
+    /**
+     * Resolve a requested mode to one this session can actually honour.
+     *
+     * A planning mode needs a wired `planRunner`; without one it degrades to the
+     * non-planning mode with the same approval behaviour rather than half-engaging
+     * (plan directive injected, nothing orchestrating it). Auto-approve is
+     * unaffected — it needs nothing wired.
+     *
+     * Unknown strings (a journal from a newer build, a hand-edited log) fall back
+     * to the default. Failing closed matters here specifically: the fallback must
+     * be the mode that asks MORE, never one that asks less.
+     */
+    resolveMode(want) {
+        const mode = parseMode(String(want)) ?? DEFAULT_MODE;
+        if (!modePlans(mode) || this.args.planRunner !== undefined)
+            return mode;
+        return mode === "full-auto" ? "auto-approve" : "manual";
+    }
+    /**
+     * Record everything appended to `current` since the last flush.
+     *
+     * Callers must only pass a history whose first `recordedCount` messages are
+     * unchanged — every call site satisfies this because the only operation that
+     * rewrites the head is compaction, which updates the watermark itself.
+     */
+    flushRecorded(current) {
+        if (!this.args.recorder)
+            return;
+        if (current.length <= this.recordedCount)
+            return;
+        this.args.recorder.append(current.slice(this.recordedCount));
+        this.recordedCount = current.length;
     }
     /** The ambient tool capabilities (gate + sandbox + cwd/config). Exposed so a
      * shell-bound custom slash command (C.19) runs through the SAME gated path. */
     get toolContext() {
         return this.args.ctx;
     }
+    /**
+     * The tool catalogue advertised to the model this session — the one
+     * `registerRuntimeTools` built, so it reflects which optional families
+     * (memory, LSP, web, MCP, subagents, jobs) are actually enabled. Exposed
+     * read-only, for `/status` to count.
+     */
+    get toolRegistry() {
+        return this.args.registry;
+    }
     /** The background-job manager (C.28), or undefined when jobs are disabled.
      * The REPL uses it to service paused-job approvals and drive `/jobs`; `cruxy
      * run` uses it to cancel every live job on exit. */
     get jobs() {
         return this.args.jobs;
     }
-    /** Whether plan mode is currently on. */
-    getPlanMode() {
-        return this.planMode;
+    /**
+     * The session's live model choice (P6 track 1), or undefined when tiers do not
+     * apply — a bring-your-own provider has no cruxy tiers to choose between, and
+     * `/model` says so rather than offering a menu that could not take effect.
+     *
+     * Exposed as the object rather than proxied through `getModel`/`setModel`
+     * accessors, because the renderer needs to SUBSCRIBE to it, not just read it:
+     * the model panel and the status line have to react to a change within the
+     * same paint, and a getter pair cannot carry that.
+     */
+    get model() {
+        return this.args.model;
+    }
+    /** The session's current mode. */
+    getMode() {
+        return this.mode;
     }
     /**
-     * Toggle plan mode. Only takes effect when a `planRunner` was wired (built by
-     * the session factory); without one, plan mode stays off.
+     * Set the mode. Returns the EFFECTIVE mode, which differs from the request
+     * when no plan runner is wired — so a caller reports what happened rather
+     * than what it asked for.
      */
-    setPlanMode(enabled) {
-        this.planMode = enabled && this.args.planRunner !== undefined;
+    setMode(mode) {
+        this.mode = this.resolveMode(mode);
+        // Record the effective value, not the request: the log must say what the
+        // session actually did.
+        this.args.recorder?.mode(this.mode);
+        return this.mode;
+    }
+    /** Advance one step around the mode ring (Shift+Tab). Returns the new mode. */
+    cycleMode() {
+        return this.setMode(nextMode(this.mode));
+    }
+    /** Whether this session proposes a plan before executing (C.31). */
+    getPlanMode() {
+        return modePlans(this.mode);
+    }
+    /** Whether gated actions run without a prompt in this session. */
+    getAutoApprove() {
+        return modeAutoApproves(this.mode);
     }
     /**
      * Run one user turn: append the prompt, compact if the history has grown past
@@ -107,6 +194,9 @@ export class Session {
         for (const tool of this.args.registry.list())
             tool.onTurnStart?.();
         this.messages.push({ role: "user", content: userPrompt });
+        // Record the user's turn before anything can fail (P2): a turn that dies in
+        // the provider still leaves what the user asked for on disk.
+        this.flushRecorded(this.messages);
         // Usage telemetry (C.22): one collector per run. `onReq` is threaded into
         // every real model request this turn drives — the main loop, compaction, and
         // (in plan mode) the propose + execution steps — so usage is captured exactly
@@ -137,7 +227,7 @@ export class Session {
         // Plan mode (C.31) delegates the whole turn to the injected runner: propose a
         // plan, approve/revise, then execute step-by-step. Falls back to the normal
         // single-shot loop when off or unwired, so existing behavior is untouched.
-        const result = this.planMode && this.args.planRunner
+        const result = modePlans(this.mode) && this.args.planRunner
             ? await this.args.planRunner({
                 messages: this.messages,
                 projectInstructions: this.projectInstructions,
@@ -167,6 +257,15 @@ export class Session {
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
         this.usage.output_tokens += result.usage.output_tokens;
+        // Persist what the turn produced (P2). The loop's mid-iteration flushes
+        // (via the compaction seam) already recorded most of it; this catches the
+        // tail after the final iteration. Usage is copied into the session log
+        // rather than referenced, because the usage store keeps only its newest 50
+        // runs while sessions are kept indefinitely.
+        this.flushRecorded(this.messages);
+        if (result.usage.input_tokens > 0 || result.usage.output_tokens > 0) {
+            this.args.recorder?.usage(result.usage.input_tokens, result.usage.output_tokens);
+        }
         // Publish the run's usage record (C.22): stash it for the one-shot summary
         // and hand it to the persistence sink. Building the record never touches the
         // network and never blocks the turn's result.
@@ -191,6 +290,11 @@ export class Session {
     /** Drop the conversation history but keep the session (for `/clear`). */
     clear() {
         this.messages = [];
+        // The log keeps every earlier message — `clear` is an event, not an
+        // erasure. Replay honours it, so a resumed session starts empty exactly as
+        // the live one did, while the transcript of what was said survives.
+        this.args.recorder?.clear();
+        this.recordedCount = 0;
     }
     /**
      * Compact `this.messages` only when it has grown past threshold, adopting the
@@ -212,6 +316,16 @@ export class Session {
      * unchanged — cheap, no model call.
      */
     async compactLoopHistory(messages, onRequestUsage) {
+        // Flush BEFORE compacting (P2). The loop owns this array and only ever
+        // appends to it between calls, so everything since the last flush is a pure
+        // append — and it has to be on disk before a compaction event can refer to
+        // a prefix length, or the recorded `replaced` count would be measured
+        // against a shorter history than the one being compacted.
+        //
+        // The loop calls this at the TOP of each iteration, after the previous
+        // iteration resolved all its tool calls, so the history flushed here is
+        // always coherent: no tool_use is ever recorded without its tool_result.
+        this.flushRecorded(messages);
         const result = await this.compactIfOverThreshold(messages, onRequestUsage);
         return result.messages;
     }
@@ -257,7 +371,12 @@ export class Session {
      * the summary's usage into the session total.
      */
     async runCompaction(messages, onRequestUsage) {
-        const cut = this.findCut(messages);
+        // Self-contained sync (P2): whatever array is about to be rewritten must be
+        // fully recorded first, so the `replaced` count in the compaction event is
+        // measured against the same history a replay will have reconstructed. A
+        // no-op when the caller already flushed, which every caller does.
+        this.flushRecorded(messages);
+        const cut = findCut(messages, this.args.config.context.keepRecentMessages);
         if (cut === null)
             return { messages, compacted: null };
         const prefix = messages.slice(0, cut);
@@ -286,37 +405,20 @@ export class Session {
                 content: `${COMPACTION_MARKER} Summary of the conversation so far:\n\n${synopsis}`,
             },
         ];
+        // Record the rewrite as an EVENT (P2): the log stays append-only, and the
+        // messages that were folded away remain readable earlier in the file even
+        // though the model can no longer see them. The watermark moves to the
+        // post-compaction length so the next append is measured against the new
+        // array, not the old one.
+        if (this.args.recorder) {
+            this.args.recorder.compaction(prefix.length, summaryMessages);
+            this.recordedCount = summaryMessages.length + kept.length;
+        }
         return {
             messages: [...summaryMessages, ...kept],
             compacted: prefix.length,
         };
     }
-    /**
-     * Choose the boundary between the summarized prefix and the kept-recent tail.
-     *
-     * Tool-call integrity is the constraint: a `tool_use` (assistant) and its
-     * matching `tool_result` (the next user message) must never straddle the cut,
-     * or the next provider call breaks. A real user *prompt* (`role:"user"` with
-     * string content) only occurs at a completed turn boundary, where every prior
-     * tool exchange is already resolved — so the kept region must begin there. The
-     * synthetic compaction-summary user message is also string content, so a
-     * repeat compaction always finds at least the previous summary as a clean cut.
-     *
-     * Start from `length - keepRecentMessages` and walk *backwards* to the nearest
-     * such prompt: this keeps at least the recent floor and lands clean. Returns
-     * the cut index, or `null` if no safe boundary leaves a non-empty prefix
-     * (e.g. a single long in-progress turn — nothing safe to compact).
-     */
-    findCut(messages) {
-        const { keepRecentMessages } = this.args.config.context;
-        const start = messages.length - keepRecentMessages;
-        for (let i = start; i >= 1; i--) {
-            const msg = messages[i];
-            if (msg.role === "user" && typeof msg.content === "string")
-                return i;
-        }
-        return null;
-    }
     /**
      * Summarize a prefix via a standalone, tool-less provider call over a rendered
      * transcript. Throws on a stream error or empty output so callers fail open.