mini-code-cli 0.1.1.0__py3-none-any.whl → 0.1.1.2__py3-none-any.whl

mini_code_cli/agent_loop.py

@@ -18,9 +18,9 @@ smaller, focused modules so each concern is easy to read and test:
   * :mod:`mini_code_cli.subagents`   -- delegating a task to a sub-agent.
   * :mod:`mini_code_cli.skills`      -- the ``.mini`` skills feature.
 
-For backward compatibility (and the test-suite) the most commonly imported
-helpers are re-exported from here, so ``from mini_code_cli.agent_loop import ...``
-keeps working.
+The helpers the test-suite imports from here are re-exported through
+``__all__``, so ``from mini_code_cli.agent_loop import save_history, ...`` works
+without the tests reaching into every module.
 """
 
 import os
@@ -50,11 +50,12 @@ from .persistence import (
     save_summary,
     save_usage_segment,
     save_total_usage,
-    load_history,
-    load_history_from_dir,
+    load_history_with_index,
     load_summary_from_dir,
     load_usage_segment,
     load_total_usage_from_dir,
+    delete_segments_above,
+    history_segment_indices,
     empty_usage,
     find_last_session_dir,
     save_last_session_pointer,
@@ -72,7 +73,7 @@ from .runner import call_function_with_timeout
 
 
 __all__ = [
-    # re-exported helpers (kept for the test-suite / external callers)
+    # re-exported helpers (imported from here by the test-suite)
     "is_within_allowed_dir",
     "tool_paths_are_allowed",
     "_FILE_TOOL_PATH_ARGS",
@@ -84,7 +85,6 @@ __all__ = [
     "call_function_with_timeout",
     "save_history",
     "save_summary",
-    "load_history",
     "generate_unique_id",
     "find_last_session_dir",
     # public classes / entry points
@@ -94,6 +94,25 @@ __all__ = [
 ]
 
 
+# ---------------------------------------------------------------------------
+# recorder helpers (shared by the class and the tests)
+# ---------------------------------------------------------------------------
+
+def _safe_int(value, default=0):
+    """Coerce ``value`` to ``int``, returning ``default`` when that is impossible.
+
+    Used by the *display / navigation* paths, which read a recorder that was
+    already validated at restore time but may have been hand-edited since: a
+    ``/history`` listing must render a junk field rather than crash the CLI.
+    A restore itself never comes through here -- it validates strictly instead
+    (see ``AgentSession._validate_records``).
+    """
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
 # ---------------------------------------------------------------------------
 # argument parsing
 # ---------------------------------------------------------------------------
@@ -109,7 +128,7 @@ def parse_args():
 
     # Other settings:
     parser.add_argument("--cache-dir", type=str, help=f"The cache dir for the session histories. default={DEFAULT_CACHE_LOCATION}")
-    parser.add_argument("--restore-session", type=str, help="The location of a previous session to continue. (e.g. ~/.cache/mini/sessions/1792028090823027-a9d77653/)")
+    parser.add_argument("--restore-session", type=str, help="A previous session to continue: its directory (e.g. ~/.cache/mini/sessions/1792028090823027-a9d77653/) or a bare session id under --cache-dir. A session folder must hold a summary_history.json recorder plus the history_{n}.json segment it names; anything else starts a fresh session.")
     parser.add_argument("-l","--load-last-session", action="store_true", help="Continue the most recent previous session recorded in the --allowed-dir .mini pointer, in place and without the resume prompt, instead of starting fresh. --restore-session takes precedence if also given.")
 
     # Agent behaviour related
@@ -169,8 +188,10 @@ def print_help(args):
     for command, description in (
         ("/history", "list the conversation (turn number, what happened, where)"),
         ("/history <n>", "show the full messages recorded for turn n"),
+        ("/history last", "...for the most recent turn"),
         ("/plan", "show the current goal + plan (plan mode only)"),
-        ("/reset [<n>]", "rewind to the end of turn n (drops everything after it)"),
+        ("/reset [<n>|last]", "rewind to the end of turn n (drops everything after it);"),
+        ("", "a bare /reset only re-saves the current state (no data loss)"),
         ("/clear", "clear the screen (keeps the conversation history)"),
         ("/help", "show this help"),
         ("/quit, /exit", "save the session and exit"),
@@ -246,6 +267,42 @@ def _compaction_trigger(messages, token_limit, reserved_output_tokens, current_t
     return False, ""
 
 
+def _in_flight_tail(messages):
+    """Return the messages of the turn that is still in flight, or ``[]``.
+
+    Compaction rewrites the transcript, so whatever it drops is gone from the
+    conversation *and* from everything saved afterwards. The last turn is not
+    finished work, though: it is either the instruction being answered right now
+    (the transcript ends with a ``user`` message) or the tool exchange the model
+    is waiting on (it ends with a ``tool`` result). Either way it has to be
+    carried across verbatim, or the model answers the summary instead of the
+    user's request -- and the typed line never reaches the recorder, the new
+    segment or a later restore.
+
+    The suffix starts at the last ``user`` message, which always begins a
+    self-contained turn: every ``assistant`` tool call inside it is followed by
+    its ``tool`` results, so the slice is a valid transcript on its own.
+
+    ``[]`` when the transcript already ends with an ``assistant`` reply: that
+    turn is answered, and re-sending it would ask the model to answer it twice.
+    """
+    if not messages:
+        return []
+    last = messages[-1]
+    if not isinstance(last, dict) or last.get("role") == "assistant":
+        return []
+    for index in range(len(messages) - 1, -1, -1):
+        message = messages[index]
+        if isinstance(message, dict) and message.get("role") == "user":
+            return list(messages[index:])
+    return []
+
+
+def _plural(count, noun, suffix="s"):
+    """``"1 message"`` / ``"4 messages"`` -- for messages the user reads."""
+    return f"{count} {noun}" + ("" if count == 1 else suffix)
+
+
 def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats,
                   history_index=0, token_limit=None, reserved_output_tokens=0,
                   current_tokens=None, plan_hook=None, console=None):
@@ -258,7 +315,9 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
     against ``token_limit``. Nothing else triggers compaction: in particular the
     number of messages is not a criterion. Compaction is then done by asking the
     LLM to summarize the history and replacing the old turns with that summary,
-    keeping the original system prompt as the first message. The compaction call
+    keeping the original system prompt as the first message *and the turn that is
+    still in flight* (see :func:`_in_flight_tail`) verbatim after it -- a summary
+    of the user's current request is not the request. The compaction call
     itself is a single, tool-free request, so it cannot trigger further tool
     calls or recurse into compaction.
 
@@ -268,10 +327,12 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
     ``plan_hook`` is an optional callable the caller supplies only when running
     under plan mode (in practice ``AgentSession._handle_compaction``). After the
     summary is built the hook re-injects the running goal + plan so the compacted
-    messages carry them forward. It receives the compacted list and must update it
-    *in place*, because that list is what gets returned to the caller. Passing it in -- instead of referencing the
-    owning session -- keeps ``maybe_compact`` a small, module-level, network-free
-    helper that the test-suite can import and exercise directly.
+    messages carry them forward. It receives the compacted list *and* the
+    in-flight tail (see below) and must update the compacted list in place,
+    because that list is what gets returned to the caller. Passing it in --
+    instead of referencing the owning session -- keeps ``maybe_compact`` a
+    small, module-level, network-free helper that the test-suite can import and
+    exercise directly.
     """
     # ``console`` defaults to None so callers may omit it, but every branch below
     # reports through a console. Falling back to the shared one keeps the
@@ -290,8 +351,20 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
         # bare messages would crash them.
         return messages, False, history_index
 
+    # The turn this step is answering -- the instruction just typed, or the tool
+    # exchange the model is waiting on -- is carried across the rollover (see
+    # :func:`_in_flight_tail`). It is computed *before* the slow summary call so
+    # the console can tell the user right away that nothing they just sent is at
+    # stake; a compaction note that stays silent about that is exactly what makes
+    # the rollover look like it might have eaten the message.
+    tail = _in_flight_tail(messages)
+    kept_note = (f" The current turn ({_plural(len(tail), 'message')}) is kept "
+                 f"verbatim." if tail else "")
+
     try:
-        console.note(f"Compacting conversation history ({reason}) -> summary...", "warn")
+        console.note(
+            f"Compacting the conversation: {_plural(len(messages), 'message')} "
+            f"-> a summary ({reason}).{kept_note}", "warn")
         summary_prompt = prompts.compaction_prompt(messages)
 
         # The summariser sometimes answers with nothing at all. An empty summary
@@ -303,7 +376,7 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
         # the over-cap transcript was retried, and paid for, on every step.
         summary = ""
         for attempt in (1, 2):
-            console.start_thinking("compacting")
+            console.start_thinking("compacting history")
             try:
                 reply, _, compact_usage, _ = utils.unpack_llm_result(
                     utils.call_openai_server(
@@ -326,9 +399,14 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
                 console.note("The summariser returned an empty summary; retrying once.", "warn")
 
         if not summary:
+            # Say plainly what did *not* happen: nothing was dropped and the
+            # segment did not move -- only the shrink did, so the next request
+            # may still be too large.
             console.note(
                 f"Could not compact history: the summariser returned an empty "
-                f"summary twice. Keeping all {len(messages)} messages "
+                f"summary twice. Keeping all {_plural(len(messages), 'message')} "
+                f"and history_{history_index}.json as they are -- nothing was "
+                f"lost, but the next request may still be too large "
                 f"({reason}).", "warn")
             return messages, False, history_index
 
@@ -341,22 +419,56 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
             "content": f"Here is a summary of our earlier conversation so far:\n{summary}",
         })
 
+        # The turn in flight has to survive the rollover. Compaction runs at the
+        # *start* of a step, so ``messages`` normally ends with the user message
+        # this step is meant to answer, or with the tool result the model is
+        # waiting on. Replacing the transcript with just (system, summary)
+        # therefore dropped the user's instruction on the floor: the model
+        # answered the summary -- "Understood. What would you like me to do?" --
+        # and the typed line never reached the new segment, the recorder or a
+        # later restore (it survived only inside the *closed* segment, which no
+        # recorder record points at any more). ``tail`` was computed before the
+        # summary call so the opening note could already promise this.
+
         # In plan mode, re-inject the running plan + current goal so a
         # compaction (which would otherwise drop them) keeps the model
         # working against the goal it is still trying to finish. The hook is
         # wired in only when the caller runs under plan mode; otherwise
-        # compaction degrades to a plain summary.
+        # compaction degrades to a plain summary. It is also handed the tail so
+        # it can restate the *real* instruction rather than the summary text.
         if plan_hook is not None:
-            plan_hook(compacted)
-
-        console.note(f"History compacted to {len(compacted)} messages.", "warn")
+            plan_hook(compacted, tail)
+
+        # ... and only then the live turn, so the user's actual instruction
+        # reads as the most recent thing the model has to act on.
+        compacted.extend(tail)
+
+        # What the user is shown has to answer the three questions a rollover
+        # raises: *what* was folded away (the summary itself), *how much* (the
+        # closing segment's message count, and what the new one starts with),
+        # and *where it went* (which segment file was closed and which was
+        # started).
+        console.note(f"Summary preview: {utils.oneline(summary, 120)}", "warn")
+        kept = (f"summary + {_plural(len(tail), 'kept message')}" if tail
+                else "summary only")
+        # Phrased as "old segment -> new segment" rather than "N messages -> M
+        # messages": the replacement can be *longer* than what it replaced (a
+        # system prompt, the summary and the kept turn), and a bare pair of
+        # counts that sometimes grows reads like a bug.
+        console.note(
+            f"Compacted history_{history_index}.json "
+            f"({_plural(len(messages), 'message')}) into a summary; "
+            f"history_{history_index + 1}.json now starts with "
+            f"{_plural(len(compacted), 'message')} ({kept}).", "warn")
         # A new segment (history_index + 1) is started on compaction: the
         # compacted messages are its snapshot, and every later turn appends
         # to it. The caller records a single high-level 'summary' turn for
         # this index so the recorder stays flat across the rollover.
         return compacted, True, history_index + 1
     except Exception as e:
-        console.note(f"Failed to compact history: {e}", "error")
+        console.note(
+            f"Failed to compact history: {e}. Keeping all "
+            f"{_plural(len(messages), 'message')} unchanged.", "error")
 
     return messages, False, history_index
 
@@ -406,6 +518,11 @@ class AgentSession:
 
         self.plan_mode = bool(getattr(self.args, "plan", False))
 
+        # The good-bye box is printed once, from shutdown(). Several exits
+        # funnel through there (quit, exit, EOF, a /quit command) and a repeated
+        # box would read like a second session had ended.
+        self._farewell_shown = False
+
         # Token accounting. ``token_stats`` covers the *current history
         # segment* and is reset when compaction rolls over to a new one;
         # ``total_usage`` is the whole-session accumulator and never decreases.
@@ -447,6 +564,12 @@ class AgentSession:
         pointer nor offers the interactive resume prompt, so it always begins a
         fresh isolated session. That is what makes delegation safe to run
         unattended -- there is a single place that decides this.
+
+        All three ways in (``--restore-session``, ``--load-last-session`` and the
+        interactive offer) go through :meth:`_try_restore`, which reports *why* a
+        restore was refused and then leaves the session clean for
+        :meth:`start_new_session`. A refused restore therefore never silently
+        reuses the old folder.
         """
         if self.background_mode and not self.restore_session:
             self.start_new_session()
@@ -469,13 +592,24 @@ class AgentSession:
     def _try_restore(self, restore_directory):
         """Restore a session in place, returning whether it worked.
 
-        A restore failure is not fatal: the caller falls back to a fresh session,
-        so a corrupt or half-written folder never blocks the CLI from starting.
+        A failed restore is not fatal: the caller falls back to a fresh session,
+        so a folder this version cannot read (or a typo'd path) never blocks the
+        CLI from starting. It is not silent either -- the reason is noted by
+        :meth:`restore_previous_session` and the fallback is announced here,
+        because a user who asked to continue a conversation needs to know that
+        they are not looking at it.
         """
         try:
-            return bool(self.restore_previous_session(restore_directory))
-        except Exception:
-            return False
+            if self.restore_previous_session(restore_directory):
+                return True
+        except Exception as e:
+            self.console.note(
+                f"Could not restore {restore_directory}: {e}", "error")
+            self._fail_restore()
+        self.console.note(
+            f"Starting a fresh session instead of restoring {restore_directory}.",
+            "warn")
+        return False
 
     def _resume_previous(self, detected):
         """Continue the detected session if the user wants to; True if restored.
@@ -505,6 +639,13 @@ class AgentSession:
         The id is normally minted in ``__init__`` (see there) and simply reused
         here; it is re-minted only when it is missing, which is what happens
         after a failed restore has cleared it.
+
+        The complete on-disk set is written straight away -- the segment, the
+        recorder and the (all-zero) usage files -- so a session this version
+        creates always satisfies the restore contract even if the process dies
+        before the first quit. A restorable session needs the recorder and the
+        segment it names; the usage files are optional, and writing them here
+        keeps the folder self-describing rather than half-populated.
         """
         self.unique_id = self.unique_id or generate_unique_id()
         self.session_dir = os.path.join(self.cache_dir, self.unique_id)
@@ -519,6 +660,9 @@ class AgentSession:
 
         save_history(self.messages, self.cache_dir, self.unique_id, self.history_index)
         save_summary(self.summary, self.cache_dir, self.unique_id)
+        save_usage_segment(self.token_stats, self.cache_dir, self.unique_id,
+                           self.history_index)
+        save_total_usage(self.total_usage, self.cache_dir, self.unique_id)
 
         # Record this session in --allowed-dir/.mini so a later
         # --load-last-session (or the interactive resume offer) can find it.
@@ -526,51 +670,106 @@ class AgentSession:
 
 
     def restore_previous_session(self, restore_directory):
-        """A function to restore from a directory.
-
-        Order matters here. ``self.messages`` must be loaded *before* the
-        recorder is restored, because the legacy fallback in
-        :meth:`_load_summary_if_restored` rebuilds the recorder by scanning the
-        restored messages. ``self.summary`` / ``self.history_index`` are seeded
-        first so that fallback can append to them and so ``_persist()`` has a
-        segment index to write to. Previously all three were unset on this path,
-        so restoring a session folder that had a ``history_N.json`` but no
-        ``summary_history.json`` (older code, or a hand-made folder) raised
-        AttributeError and the caller silently started a *new* session instead.
+        """Restore a session from ``restore_directory``, strictly, or refuse it.
+
+        A restorable folder is exactly what this version writes: a
+        ``summary_history.json`` recorder whose records name where each turn
+        lives, plus a readable ``history_{n}.json`` for the segment the *last*
+        record points at. Nothing else is accepted, and each refusal says which
+        part was wrong:
+
+          * the directory does not exist              -> refuse;
+          * no recorder (or not a JSON list)          -> refuse;
+          * a recorder that does not validate         -> refuse (``_validate_records``);
+          * the named segment missing/empty/garbled   -> refuse.
+
+        There is deliberately no "rebuild the recorder from the transcript" path
+        and no single-file ``history.json`` fallback: both had to *invent* turn
+        boundaries, which made a rebuilt session behave differently under
+        ``/reset`` than a recorded one -- and only sessions this version wrote
+        are being restored.
+
+        Order matters, and it is recorder-first. The recorder says which segment
+        the user was really looking at, and the messages are loaded from *that*
+        one, so a ``/reset`` that rewound onto an older segment is not undone by
+        a stale higher segment left on disk. The loaded index becomes
+        ``history_index`` -- the segment later saves append to -- and only then
+        are the usage totals restored (they are looked up by that index).
+
+        Failure is atomic: :meth:`_fail_restore` clears everything a restore
+        touches, so the caller's fallback is a clean fresh session that never
+        half-adopts this folder or reuses its id.
         """
+        prefix = f"Cannot restore {restore_directory}"
+        if not restore_directory or not os.path.isdir(restore_directory):
+            self.console.note(f"{prefix}: no such session directory.", "error")
+            return self._fail_restore()
+
+        saved_summary = load_summary_from_dir(restore_directory)
+        if saved_summary is None:
+            self.console.note(
+                f"{prefix}: it has no readable summary_history.json "
+                "(the recorder every restorable session has).", "error")
+            return self._fail_restore()
+        try:
+            records = self._validate_records(saved_summary)
+        except ValueError as e:
+            self.console.note(f"{prefix}: {e}.", "error")
+            return self._fail_restore()
+
+        # A recorder with no turns is a session that quit before finishing one:
+        # it is restorable, on the segment it started on.
+        preferred = records[-1]["history_file"] if records else 0
+        restored, loaded_index = load_history_with_index(restore_directory, preferred)
+        if restored is None:
+            self.console.note(
+                f"{prefix}: history_{preferred}.json is missing, empty or "
+                "unreadable.", "error")
+            return self._fail_restore()
+
         try:
             self.unique_id = os.path.basename(os.path.normpath(restore_directory))
             self.session_dir = restore_directory
             self.plan_manager = plan_utils.PlanManager(
                 self.session_dir, enabled=self.plan_mode)
-            self.summary = []
-            self.history_index = 0
-            restored = load_history_from_dir(restore_directory) if restore_directory else None
-
-            self.messages = restored if restored is not None else self._build_initial_messages()
+            self.messages = restored
+            self.summary = records
+            self.history_index = int(loaded_index)
             # No prompt has been sent in *this* process yet, so any remembered
             # size would be stale: start from a plain estimate of the restored
             # transcript (which is what project_input_tokens falls back to).
             self.last_prompt_tokens = 0
             self.last_prompt_message_count = 0
-            # The recorder restore decides which segment we are on, so usage --
-            # which is stored per segment -- has to be restored after it.
-            self._load_summary_if_restored(restore_directory)
             self._restore_usage_if_available(restore_directory)
 
             # Continuing a session in place makes it the latest one again: keep
             # the pointer aimed at it so a later --load-last-session finds the
             # conversation the user is actually working in.
             self._save_last_session_pointer()
-
             return True
-
         except Exception as e:
-            self.unique_id = None
-            self.session_dir = None
-            self.plan_manager = None
-            return False
+            self.console.note(f"{prefix}: {e}", "error")
+            return self._fail_restore()
 
+    def _fail_restore(self):
+        """Clear every field a restore may have touched; always returns ``False``.
+
+        A restore is all-or-nothing. Dropping ``unique_id`` is what guarantees
+        the fallback really is a *fresh* session: ``start_new_session`` re-mints
+        the id when it is missing, so a refused restore can never append to (or
+        overwrite) the folder it just declined to adopt.
+        """
+        self.unique_id = None
+        self.session_dir = None
+        self.plan_manager = None
+        self.messages = []
+        self.summary = []
+        self.history_index = 0
+        self.token_stats = empty_usage()
+        self.total_usage = empty_usage()
+        self.last_prompt_tokens = 0
+        self.last_prompt_message_count = 0
+        return False
 
     def _resolve_model(self, args):
         """Pick the model id: the one the user named, else the server's default.
@@ -667,10 +866,12 @@ class AgentSession:
 
         ``token_stats`` comes from the segment we restored onto
         (``usage_{history_index}.json``) and ``total_usage`` from
-        ``total_usage.json`` (falling back to the sum of all segments), so the
-        running summary stays continuous across a restore *and* across the
-        compaction that may have happened before it. Best-effort: any problem
-        leaves the totals at zero rather than breaking the restore.
+        ``total_usage.json`` (reconstructed from the segment files when it is
+        missing), so the running totals stay continuous across a restore *and*
+        across the compaction that may have happened before it. Usage is
+        optional -- a folder that has no usage files at all still restores, with
+        zeros -- and any problem there leaves the totals at zero rather than
+        failing the restore.
         """
         segment = load_usage_segment(restore_directory, self.history_index)
         total = load_total_usage_from_dir(restore_directory)
@@ -770,29 +971,52 @@ class AgentSession:
             if delta > 0:
                 self.total_usage[key] = self.total_usage.get(key, 0) + delta
 
-    def _load_summary_if_restored(self, restore_directory):
-        """Restore the high-level recorder and segment index for a restore.
-
-        Prefers the saved ``summary_history.json`` so the recorder stays flat and
-        contiguous across the restore, seeding ``self.summary`` and the next
-        ``history_index`` from its last record. If no recorder was saved (e.g. a
-        session created by older code, or only a classic ``history.json``), we
-        rebuild a minimal recorder by scanning the restored messages for
-        assistant turns, so navigation still works. Best-effort only.
+    @staticmethod
+    def _validate_records(saved):
+        """Validate a loaded recorder strictly; return a clean copy of its records.
+
+        A ``summary_history.json`` is the *contract* the navigation layer runs
+        on: ``/history <n>`` and ``/reset <n>`` index into the list positionally
+        and every record says exactly where its turn lives on disk
+        (``history_{n}.json`` at message ``index``). A malformed record
+        therefore cannot be repaired without inventing a location, so this
+        raises ``ValueError`` naming the offending record instead of normalising
+        it -- the restore is then refused and the user starts a fresh session,
+        which is honest. (The old lenient pass silently dropped junk entries,
+        clamped negatives at 0 and renumbered turns ``1..N``; one dropped record
+        shifted every later turn number and made a rewind land in the wrong
+        place while still reporting success.)
+
+        Requirements: a JSON list of objects, each with integer ``turn`` /
+        ``history_file`` / ``index``, no negative ``history_file`` or ``index``,
+        and ``turn == position + 1`` (turns run contiguously from 1). An empty
+        list is valid -- a session that quit before finishing a turn.
         """
-        saved = load_summary_from_dir(restore_directory)
-
-        saved = [r for r in saved if isinstance(r, dict)]
-        if saved:
-            self.summary = saved
-            self.history_index = int(saved[-1].get("history_file", 0))
-            return
-        turn = 0
-        for i, m in enumerate(self.messages):
-            if m.get("role") == "assistant":
-                turn += 1
-                self.summary.append({"turn": turn, "what": "assistant",
-                                     "history_file": 0, "index": i})
+        if not isinstance(saved, list):
+            raise ValueError("summary_history.json does not hold a list of turns")
+        records = []
+        for position, entry in enumerate(saved, start=1):
+            if not isinstance(entry, dict):
+                raise ValueError(f"record {position} is not a JSON object")
+            for key in ("turn", "history_file", "index"):
+                value = entry.get(key)
+                if not isinstance(value, int) or isinstance(value, bool):
+                    raise ValueError(
+                        f"record {position} has a non-integer {key} ({value!r})")
+            if entry["turn"] != position:
+                raise ValueError(
+                    f"record {position} is numbered turn {entry['turn']} "
+                    f"(turns must run 1..{len(saved)})")
+            if entry["history_file"] < 0 or entry["index"] < 0:
+                raise ValueError(
+                    f"record {position} has a negative history_file/index")
+            records.append({
+                "turn": entry["turn"],
+                "what": str(entry.get("what") or "?"),
+                "history_file": entry["history_file"],
+                "index": entry["index"],
+            })
+        return records
 
     def _record_turn(self, what, messages, history_index=None):
         """Append one entry to the high-level recorder.
@@ -815,64 +1039,193 @@ class AgentSession:
 
     def _show_history(self):
         """Print the high-level recorder as a numbered list of turns."""
-        rows = [(str(r.get("turn", i + 1)),
-                 r.get("what", "?"),
-                 f"history_{r.get('history_file', 0)}.json#{r.get('index', 0)}")
-                for i, r in enumerate(self.summary)]
+        if not self.summary:
+            self.console.note("No history has been recorded yet.", "warn")
+            return
+        rows = [(str(_safe_int(r.get("turn", i + 1), i + 1)),
+                 str(r.get("what") or "?"),
+                 f"history_{_safe_int(r.get('history_file'), 0)}.json"
+                 f"#{_safe_int(r.get('index'), 0)}")
+                for i, r in enumerate(self.summary) if isinstance(r, dict)]
         self.console.history_list(rows)
 
+    def _resolve_turn_record(self, arg):
+        """Resolve a turn selector to ``(position, record)``, or ``None``.
+
+        One rule for both ``/history <n>`` and ``/reset <n>``: accept ``last``
+        (case-insensitive) or a **positive** 1-based integer, and reject
+        everything else with the same message -- ``0``, negatives, non-integers
+        and out-of-range values. Previously ``/history`` computed
+        ``summary[int(arg) - 1]`` without a lower bound, so ``/history 0``
+        silently showed the *last* turn and ``/history -2`` the third-to-last,
+        while ``/reset`` rejected exactly those inputs: the same user mistake got
+        two different (and one silently wrong) answers.
+        """
+        count = len(self.summary)
+        if not count:
+            self.console.note("No history has been recorded yet.", "warn")
+            return None
+        text = (arg or "").strip().lower()
+        if text in ("last", ""):
+            return count - 1, self.summary[-1]
+        try:
+            position = int(text) - 1
+        except (TypeError, ValueError):
+            position = -1
+        if not 0 <= position < count:
+            self.console.note(
+                f"No such turn {arg!r} (have 1..{count}, or 'last').", "error")
+            return None
+        return position, self.summary[position]
+
     def _inspect_history(self, arg):
         """Print the full messages recorded for a single turn."""
-        try:
-            record = self.summary[-1] if arg == "last" else self.summary[int(arg) - 1]
-        except (ValueError, IndexError):
-            self.console.note(f"No such turn {arg!r} (have 1..{len(self.summary)}).", "error")
+        resolved = self._resolve_turn_record(arg)
+        if resolved is None:
             return
+        _, record = resolved
         messages = self._segment_upto(record)
         if messages is None:
             return
         self.console.history_detail(record, messages, total=len(self.summary))
 
+    def _load_segment(self, history_index):
+        """Load ``history_{history_index}.json`` as a message list, or ``None``.
+
+        Never raises and never trusts the argument: an out-of-range, negative or
+        non-integer index, a missing file, unreadable JSON or a payload that is
+        not a non-empty list all yield ``None``. Navigation and the rewind only
+        ever *read* through here, so a damaged segment can never crash the CLI.
+        """
+        index = _safe_int(history_index, -1)
+        if index < 0 or not self.session_dir:
+            return None
+        path = os.path.join(self.session_dir, f"history_{index}.json")
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                segment = json.load(f)
+        except Exception:
+            return None
+        if not isinstance(segment, list) or not segment:
+            return None
+        return [m for m in segment if isinstance(m, dict)]
+
+    def _segment_for(self, history_index):
+        """Return the messages of a segment, preferring the live transcript.
+
+        ``_persist()`` only runs on quit (and at a compaction rollover), so the
+        ``history_{n}.json`` file on disk can lag arbitrarily far behind the
+        running conversation. For the *current* segment the in-memory transcript
+        is therefore the authoritative copy -- reading the file instead used to
+        silently drop everything said since the last save (a ``/reset`` could
+        truncate to a state older than the turn it was asked to keep). Older
+        segments are immutable within their lifetime, so they are read from disk.
+        """
+        index = _safe_int(history_index, -1)
+        if index < 0:
+            return None
+        if index == self.history_index:
+            live = [m for m in self.messages if isinstance(m, dict)]
+            if live:
+                return live
+        return self._load_segment(index)
+
     def _segment_upto(self, record):
         """Load a recorded turn's segment and truncate it at its index.
 
         Returns the messages reproducing the conversation state at the end of
         that turn, or None if the segment could not be loaded (never raises: a
-        missing or moved segment must not crash navigation).
+        missing or moved segment must not crash navigation). Both recorded
+        numbers are coerced and the index is clamped into the segment, so a
+        stale or hand-edited recorder entry cannot slice outside it.
         """
-        segment_path = os.path.join(
-            self.session_dir, f"history_{record.get('history_file', 0)}.json")
-        try:
-            with open(segment_path, "r", encoding="utf-8") as f:
-                segment = json.load(f)
-        except Exception:
+        segment = self._segment_for(record.get("history_file"))
+        if not segment:
             self.console.note("Could not load the history segment for that turn.", "error")
             return None
-        idx = max(0, min(int(record.get("index", 0)), len(segment) - 1))
-        return segment[:idx + 1]
+        index = max(0, min(_safe_int(record.get("index"), 0), len(segment) - 1))
+        return segment[:index + 1]
 
-    def _reset_history(self, keep, record):
+    def _reset_history(self, keep_count, record, force=True):
         """Rewind the conversation to the end of a recorded turn.
 
-        Rebuilds ``self.messages`` from the turn's recorded segment + index,
-        moves the session back onto that segment (``history_index``) and drops
-        everything after it -- both the extra messages and the later recorder
-        entries. New turns then continue from that state. Best-effort only: a
-        segment that cannot be loaded leaves the session unchanged.
+        ``keep_count`` is how many recorder entries to keep (the resolved
+        position + 1 -- *not* ``record["turn"]``, which is display data and used
+        to be trusted for slicing). The work is ordered so a failure cannot leave
+        the live session remembering a state the disk did not accept:
+
+          1. load the target segment and compute the truncated transcript;
+          2. refuse (with a warning) when ``force`` is off and messages after the
+             recorded turn exist -- an unrecorded tail must not be silently
+             destroyed;
+          3. persist the truncated ``history_{n}.json``, ``summary_history.json``
+             and ``total_usage.json`` *first*, rolling the segment/summary back
+             if either write fails;
+          4. delete the now-orphaned higher segments (best-effort: a failure is
+             a warning, not a rollback -- the rewind is already on disk);
+          5. only then mutate the live session.
+
+        Afterwards the session is really on segment ``n``: ``token_stats`` is
+        reloaded from ``usage_{n}.json`` (so the next ``_persist()`` cannot write
+        the later segment's counters over it), the remembered prompt size is
+        dropped (it describes a transcript that no longer exists) and
+        ``total_usage`` is left alone -- a rewind does not un-spend tokens.
         """
-        messages = self._segment_upto(record)
-        if messages is None:
-            return
+        target_index = _safe_int(record.get("history_file"), -1)
+        full_segment = self._segment_for(target_index)
+        if full_segment is None:
+            self.console.note(
+                "Could not load the history segment for that turn; "
+                "the session is unchanged.", "error")
+            return False
+
+        index = max(0, min(_safe_int(record.get("index"), 0), len(full_segment) - 1))
+        messages = full_segment[:index + 1]
+        trailing = max(len(full_segment) - len(messages), 0)
+        if not force and trailing:
+            self.console.note(
+                f"{trailing} message(s) after turn {keep_count} were never recorded; "
+                f"refusing to discard them. Use /reset {keep_count} to rewind anyway.",
+                "warn")
+            return False
+
+        new_summary = [r for r in self.summary[:keep_count] if isinstance(r, dict)]
+        try:
+            save_history(messages, self.cache_dir, self.unique_id, target_index)
+            save_summary(new_summary, self.cache_dir, self.unique_id)
+            save_total_usage(self.total_usage, self.cache_dir, self.unique_id)
+        except Exception as e:
+            # Put the untouched segment and recorder back, so the on-disk state
+            # still matches the (unchanged) in-memory session.
+            try:
+                save_history(full_segment, self.cache_dir, self.unique_id, target_index)
+                save_summary(self.summary, self.cache_dir, self.unique_id)
+            except Exception:
+                pass
+            self.console.note(
+                f"Could not persist the rewind ({e}); the session is unchanged.", "error")
+            return False
+
+        removed = delete_segments_above(self.session_dir, target_index)
+
         self.messages = messages
-        self.history_index = int(record.get("history_file", 0))
-        self.summary = self.summary[:keep]
-        save_history(self.messages, self.cache_dir, self.unique_id, self.history_index)
-        save_summary(self.summary, self.cache_dir, self.unique_id)
+        self.history_index = target_index
+        self.summary = new_summary
+        self.token_stats = load_usage_segment(self.session_dir, target_index)
+        self.last_prompt_tokens = 0
+        self.last_prompt_message_count = 0
+
         self.console.note(
-            f"Reset to turn {keep}: kept {len(self.messages)} messages "
-            f"(history_{self.history_index}.json up to index "
-            f"{int(record.get('index', 0))}).", "ok")
+            f"Reset to turn {keep_count}: kept {len(self.messages)} messages "
+            f"(history_{target_index}.json up to index {index}).", "ok")
+        if removed:
+            # Reported at "ok" level, not "info": info notes are hidden in the
+            # default (non-verbose) view, which is exactly where the user needs to
+            # know that files were deleted.
+            self.console.note(
+                f"Removed {len(removed)} later history/usage segment file(s).", "ok")
         self.console.note("Continuing: new turns will append to this state.", "info")
+        return True
 
     def _warn_sudo(self):
         """Print a prominent red warning about --sudo mode.
@@ -1006,8 +1359,12 @@ class AgentSession:
             return
         except KeyboardInterrupt:
             self.console.note("Interrupting: Mini Code Exiting...", "error")
+            self.shutdown(farewell=False)
+            return
         except Exception as e:
             self.console.note(f"Exception {e}. Exiting...", "error")
+            self.shutdown(farewell=False)
+            return
         self.shutdown()
 
     def _emit_tip(self):
@@ -1251,7 +1608,7 @@ class AgentSession:
         return True
 
 
-    def _handle_compaction(self, compacted):
+    def _handle_compaction(self, compacted, tail=()):
         """Re-inject goal + plan into the compacted messages (plan mode).
 
         Plan-mode counterpart to the plan handling inside :meth:`maybe_compact`,
@@ -1259,7 +1616,8 @@ class AgentSession:
         a network-free module-level helper. The loop wires in this method only
         when plan mode is on; it re-injects the goal + plan via
         :meth:`_apply_plan_to_compacted`, which also rewrites the tracking files
-        to match.
+        to match. ``tail`` is the turn that is still in flight, which
+        ``maybe_compact`` appends after the hook's messages.
 
         The hook must update ``compacted`` **in place**: ``maybe_compact``
         returns *that* list to the caller, which then assigns it to
@@ -1267,9 +1625,9 @@ class AgentSession:
         discarded a moment later, silently dropping the goal and plan -- which is
         exactly what happened before this was a slice assignment.
         """
-        compacted[:] = self._apply_plan_to_compacted(compacted)
+        compacted[:] = self._apply_plan_to_compacted(compacted, tail)
 
-    def _apply_plan_to_compacted(self, messages):
+    def _apply_plan_to_compacted(self, messages, tail=()):
         """Re-inject the current goal + plan after a history compaction.
 
         Compaction replaces the transcript with a summary, which would otherwise
@@ -1277,16 +1635,18 @@ class AgentSession:
         back off disk and append them as fresh user turns so the model keeps
         working against the goal it is still trying to finish. The goal is
         appended last so it reads as the most recent instruction the model
-        should act on.
+        should act on -- ``maybe_compact`` then appends the in-flight turn, which
+        is the same instruction verbatim.
         """
         plan_text = self.plan_manager.read_plan()
         goal_text = self.plan_manager.read_goal()
 
-        # Recover the user's latest instruction from the pre-compaction tail, in
-        # case the loop had not recorded a goal yet, so there is always a goal to
-        # restate after compaction.
+        # Recover the user's latest instruction from the *in-flight turn* -- not
+        # from ``messages``, which by now holds the summary -- so a session that
+        # compacts before its goal was recorded still restates the real
+        # instruction instead of the summary text.
         current_input = None
-        for m in reversed(messages):
+        for m in reversed(list(tail or ())):
             if m.get("role") == "user":
                 current_input = m.get("content")
                 break
@@ -1363,8 +1723,10 @@ class AgentSession:
           /history           list the high-level recorder (turn number, what
                              happened, and which history_{n}.json + index)
           /history <n>       show the full messages recorded for turn <n>
-          /reset [<n>]       rewind the conversation to the end of turn <n>
-                             (no <n> rewinds to the most recent turn)
+          /history last      ...for the most recent turn
+          /reset [<n>|last]  rewind the conversation to the end of turn <n>
+                             (a bare /reset only re-saves the current state;
+                             see _do_reset)
           /plan              show the current goal + plan the loop maintains
                              (plan mode only)
           /clear             clear the screen (keeps the conversation)
@@ -1404,25 +1766,38 @@ class AgentSession:
     def _do_reset(self, arg):
         """Rewind the conversation to the end of a recorded turn.
 
-        No argument resets to the most recent turn (a no-op that just replays the
-        current state). With <n>, rewinds to that turn, dropping the messages and
-        recorder entries after it.
+        ``/reset <n>`` and ``/reset last`` are *explicit* rewinds: they truncate
+        the transcript to the end of that turn and drop everything recorded after
+        it. A bare ``/reset`` is the cautious variant -- it never truncates: when
+        the transcript really ends at the last recorded turn it just reports
+        "Already at turn N", and when unrecorded messages follow that turn it
+        *warns* instead of destroying them, because the user never asked for a
+        specific turn. Forcing the rewind is one explicit command away:
+        ``/reset <n>``.
         """
-        if not self.summary:
-            self.console.note("No history has been recorded yet.", "warn")
+        resolved = self._resolve_turn_record(arg)
+        if resolved is None:
             return
-        target = self.summary[-1]
-        if arg:
-            try:
-                idx = int(arg) - 1
-                if not (0 <= idx < len(self.summary)):
-                    raise ValueError
-                target = self.summary[idx]
-            except ValueError:
-                self.console.note(
-                    f"No such turn {arg!r} (have 1..{len(self.summary)}).", "error")
-                return
-        self._reset_history(target["turn"], target)
+        position, record = resolved
+        explicit = bool((arg or "").strip())
+
+        if not explicit and self._transcript_ends_at(record):
+            self.console.note(
+                f"Already at turn {position + 1} (the last recorded turn); "
+                f"nothing to rewind. Use /reset <n> to rewind to an earlier turn.",
+                "ok")
+            return
+        self._reset_history(position + 1, record, force=explicit)
+
+    def _transcript_ends_at(self, record):
+        """Whether the live transcript is exactly the state recorded for a turn.
+
+        That is true when the session is still on the record's segment and its
+        last message is the one the record points at -- i.e. a bare ``/reset``
+        has nothing left to drop.
+        """
+        return (_safe_int(record.get("history_file"), -1) == self.history_index
+                and len(self.messages) == _safe_int(record.get("index"), -1) + 1)
 
     def _show_plan(self):
         """Show the current plan/goal the loop maintains (``/plan`` command).
@@ -1633,21 +2008,112 @@ class AgentSession:
                           badge=self._context_badge())
 
     def _persist(self):
-        save_history(self.messages, self.cache_dir, self.unique_id, self.history_index)
-        save_summary(self.summary, self.cache_dir, self.unique_id)
-        usage_path = save_usage_segment(self.token_stats, self.cache_dir,
-                                        self.unique_id, self.history_index)
-        total_path = save_total_usage(self.total_usage, self.cache_dir, self.unique_id)
-        self.console.note(
-            f"Saved usage to: {usage_path} (session total: {total_path})", "info")
+        """Write the current segment, recorder and usage totals to disk.
 
-    def shutdown(self):
-        """Persist and print a final summary (called on quit / exit)."""
+        Each write is attempted independently and none of them may raise: a full
+        disk, a read-only cache dir or a permission hiccup has to degrade to a
+        warning. Quitting must never crash, and a failed transcript save must not
+        stop the usage totals (or the other way round) from being written.
+        """
+        def attempt(label, write):
+            try:
+                return write()
+            except Exception as e:
+                self.console.note(f"Could not save the {label}: {e}", "error")
+                return None
+
+        attempt("history segment", lambda: save_history(
+            self.messages, self.cache_dir, self.unique_id, self.history_index))
+        attempt("history recorder", lambda: save_summary(
+            self.summary, self.cache_dir, self.unique_id))
+        usage_path = attempt("segment usage", lambda: save_usage_segment(
+            self.token_stats, self.cache_dir, self.unique_id, self.history_index))
+        total_path = attempt("session usage", lambda: save_total_usage(
+            self.total_usage, self.cache_dir, self.unique_id))
+        if usage_path or total_path:
+            self.console.note(
+                f"Saved usage to: {usage_path} (session total: {total_path})", "info")
+
+    def shutdown(self, farewell=True):
+        """Persist and print a final summary (called on quit / exit).
+
+        ``farewell=False`` is used by the interrupt / fatal paths in :meth:`run`,
+        which have already told the user (in red) that the session is being torn
+        down: a cheerful "thanks and here is your state" box on top of a crash is
+        the wrong note, and the state it would recap is the state that just
+        failed.
+        """
         self._persist()
+        segments = history_segment_indices(self.session_dir)
+        # List what is really on disk. The old message claimed
+        # "history_0..{history_index}.json", which was a lie after a /reset had
+        # removed the higher segments (or moved the session back onto an earlier
+        # one) -- it named files that no longer existed and hid the ones that did.
+        if segments:
+            present = (f"history_{segments[0]}.json"
+                       if len(segments) == 1 else
+                       f"history_{segments[0]}..{segments[-1]}.json")
+        else:
+            present = f"history_{self.history_index}.json"
         self.console.note(
             f"Saved session to {self.cache_dir}/{self.unique_id}/ "
-            f"(history_0..{self.history_index}.json + summary_history.json).", "ok")
-        self.console.usage_summary(self.total_usage)
+            f"({present} + summary_history.json).", "ok")
+        # The detailed per-field usage block is verbose-only (the console
+        # documents it that way); in the quiet default view the good-bye box
+        # below carries the same totals, so nothing is lost by leaving it out.
+        if self.console.verbose:
+            self.console.usage_summary(self.total_usage)
+        if farewell:
+            self._farewell(segments)
+
+    def _farewell(self, segments=None):
+        """Print the good-bye box: version, sign-off and what the session left.
+
+        Printed once (see ``_farewell_shown``) and only on a normal exit. It
+        restates the state in one glanceable place -- the same facts the user
+        would otherwise have to piece together from the save note, ``/history``
+        and the (verbose-only) usage readout, which in the quiet default view
+        means they saw none of it.
+        """
+        if self._farewell_shown:
+            return
+        self._farewell_shown = True
+        from . import __version__ as version
+
+        if segments is None:
+            segments = history_segment_indices(self.session_dir)
+        if not segments:
+            where = f"history_{self.history_index}.json"
+        elif len(segments) == 1:
+            where = f"history_{segments[0]}.json"
+        else:
+            where = f"history_{segments[0]}..{segments[-1]}.json"
+
+        turns = len(self.summary)
+        usage = self.total_usage or {}
+
+        def count(key):
+            # A display detail on the exit path must never raise: a server that
+            # reported ``null`` usage leaves a None here, and crashing while
+            # saying goodbye would be the worst possible time to fail.
+            try:
+                return int(usage.get(key) or 0)
+            except (TypeError, ValueError):
+                return 0
+
+        rows = [
+            ("session id", self.unique_id),
+            ("saved under", f"{self.cache_dir}/{self.unique_id}/"),
+            ("history", f"{where} (segment {self.history_index}), "
+                        f"{_plural(len(self.messages), 'message')}"),
+            ("conversation", _plural(turns, "recorded turn")),
+            ("tokens", f"{count('prompt_tokens'):,} in / "
+                       f"{count('completion_tokens'):,} out "
+                       f"({count('total_tokens'):,} total)"),
+            ("calls", f"{count('llm_calls'):,} LLM, "
+                      f"{count('tool_calls'):,} tool"),
+        ]
+        self.console.farewell(version, rows)
 
     # -- single LLM turn ---------------------------------------------------
 
@@ -1659,6 +2125,9 @@ class AgentSession:
         # rolls the session over to a fresh history segment (history_index + 1)
         # and returns that bump so the recorder can stay flat across it.
         segment_before = dict(self.token_stats)
+        # The segment as it stands *before* compaction: it has to be flushed to
+        # disk as it is being closed (see below), because nothing else writes it.
+        closing_messages = self.messages
         projected = self._projected_input_tokens()
         self.messages, did_compact, new_index = maybe_compact(
             self.messages, self.server_url, self.model, self.api_key,
@@ -1682,17 +2151,33 @@ class AgentSession:
             # would trigger compaction again immediately.
             self.last_prompt_tokens = 0
             self.last_prompt_message_count = 0
-            # Close the old segment's usage file before moving on, so its spend
-            # is preserved on disk even though the next segment starts at zero.
-            save_usage_segment(self.token_stats, self.cache_dir, self.unique_id,
-                               self.history_index)
+            # Close the old segment's files before moving on: its spend is
+            # preserved for the totals, and its *messages* are flushed so the
+            # recorder keeps pointing at a transcript that really exists on disk.
+            # Nothing else writes a closing segment -- the interactive loop only
+            # persists on quit -- so without this history_{n}.json would be short
+            # by every turn recorded in that segment, and /reset (or a restore)
+            # would rewind to a state the user never saw.
+            try:
+                save_usage_segment(self.token_stats, self.cache_dir, self.unique_id,
+                                   self.history_index)
+                save_history(closing_messages, self.cache_dir, self.unique_id,
+                             self.history_index)
+            except Exception as e:
+                self.console.note(
+                    f"Could not save the closed history segment "
+                    f"history_{self.history_index}.json: {e}. The compacted "
+                    f"conversation is unaffected, but /reset back into that "
+                    f"segment may be incomplete.", "warn")
             self.history_index = new_index
             self.token_stats = empty_usage()
             # Snapshot the compacted messages into the new segment so its turns
             # are preserved, and record the summary as the first turn of it.
             save_history(self.messages, self.cache_dir, self.unique_id, self.history_index)
             self._record_turn(
-                f"summary: history compacted to {len(self.messages)} messages",
+                f"summary: history_{new_index - 1}.json "
+                f"({_plural(len(closing_messages), 'message')}) compacted into a "
+                f"summary; history_{self.history_index}.json started",
                 self.messages)
 
         # Show a "… thinking" spinner while the LLM works (in-place, non-scrolling;
@@ -1785,6 +2270,13 @@ class AgentSession:
                 self.messages)
         elif response_text:
             self._record_turn("assistant", self.messages)
+        else:
+            # A step that produced neither text nor tool calls (a failed call, or
+            # a model that answered with nothing) still appended an assistant
+            # message, so it is recorded as well. The recorder must cover the
+            # *final* message: otherwise a bare /reset sees an unrecorded tail
+            # and refuses to touch a conversation that is in fact settled.
+            self._record_turn("assistant (no response)", self.messages)
 
         return made_tool_calls and self.args.auto_mode
 
@@ -1794,7 +2286,7 @@ class _Abort(Exception):
 
 
 # ---------------------------------------------------------------------------
-# module-level helpers kept for readability / backward compatibility
+# entry point
 # ---------------------------------------------------------------------------
 
 def main():