filekeeper-cli 0.1.4__tar.gz → 0.1.7__tar.gz

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: filekeeper-cli
-Version: 0.1.4
+Version: 0.1.7
 Summary: Safe, predictable filesystem operations for humans and AI agents, with atomic writes and workspace confinement.
 Keywords: filesystem,atomic-write,cli,agents,mcp
 Author: sangingeum
@@ -244,6 +244,13 @@ later file fails after earlier ones were written, the written files are rolled
 back to their pre-patch bytes and the failure names what was restored. A crash is
 resolved from the pending journal record, never from an all-or-nothing commit.
 
+When a hunk's header and its body disagree — the hunk is cut short or a line
+prefix is not ` `, `+` or `-` — the `PATCH_FAILED` error states the counts the
+header declares and the counts the body actually supplied, in the message and in
+`details.expected_old_lines`, `expected_new_lines`, `actual_old_lines` and
+`actual_new_lines`. The existing `line` and `reason` fields are still there. Patch
+text is never echoed into the error.
+
 ## Commands
 
 ```
@@ -304,10 +311,11 @@ affected path with the state the operation recorded:
 
 - if the path still matches the recorded **after** state, undo restores the
   recorded **before** bytes;
-- if it already matches the **before** state (a partially applied multi-file
-  operation), undo leaves it alone;
-- if it matches neither, someone changed it afterwards: the undo is refused with
-  `UNDO_CONFLICT` (exit code 12) and **nothing is modified**.
+- if it already matches the **before** state of an operation that never committed
+  (a partially applied multi-file operation), undo leaves it alone;
+- if a committed operation's path no longer matches the **after** state — edited,
+  deleted, or renamed away — the undo is refused with `UNDO_CONFLICT` (exit code
+  12) and **nothing is modified**.
 
 Undoing a create removes the file only while it still matches what was created.
 Undoing a delete restores the file only while the destination is still absent.
@@ -318,6 +326,18 @@ The undo is itself recorded as an operation, so `history list` remains a
 truthful ledger. **Redo is deferred** — it is not half-implemented; undoing an
 undo is the supported way to go forward again.
 
+A copy or a move records the path it read from in the operation's `metadata`
+under `source_path`, and its summary names both ends. `target_path` keeps its
+meaning — the path the operation targets — so existing readers are unaffected.
+
+A refused undo is recorded too: the ledger gains an `undo_refused` row with the
+target path, the conflict code, and the paths that blocked the undo. It changed
+nothing, so it carries no items, is never offered as undoable, and `undo-last`
+skips it. A refusal of a refusal is the one exception: undoing that
+`undo_refused` row is refused with the same coded error, but writes no second row,
+because the existing row already states the conflict. Every recorded path is
+workspace-relative, never a resolved host path.
+
 `keeper file read` writes file content to standard output unchanged (line endings
 included). Metadata goes to stderr, or into the JSON object with `--json`.
 `--input FILE` reads replacement content from a file, avoiding shell argument
@@ -380,6 +400,23 @@ re-reads the file and writes against its new hash.
 so its previous bytes were deliberately not stored; `history_skipped` then names
 the paths.
 
+**A dry run reports a preview, not a write.** With `"dry_run": true`, `changed` is
+`false`, `operation_id` and `after_hash` are `null`, and each item's `after_hash`
+and `size_bytes` are `null`: nothing was observed, so nothing is claimed. The hash
+a real run would produce appears as `predicted_after_hash` — a prediction, never an
+observation — and `would_change` says whether a real run would alter anything.
+`before_hash` and `preview_diff` are kept, because they describe the state the
+preview was computed against. The same shape applies to every mutating command and
+to the MCP tools that mirror them. A committed operation still reports
+`"changed": true` with its observed `after_hash`.
+
+`changed` and `would_change` answer different questions: `would_change` asks
+whether the bytes would differ, while `changed` records whether an operation
+executed and was journalled — so a real write of identical content reports
+`"changed": true` and adds a history row, which callers may rely on as proof a
+write completed. In a preview the two cannot disagree: when `would_change` is
+false, every item reports `"unchanged"`.
+
 Editing results add `match_stage` and `match_count` (text replacement),
 `preview_diff` (dry run), and, for patches, `patch_files` with per-hunk status.
 A failure that was rolled back reports the restored paths in the error details.
@@ -421,6 +458,13 @@ a shell predicate.
 
 Codes are stable; messages are not a contract.
 
+Messages name the interface the caller is using. A refusal that offers an
+override states that interface's own argument: Core's keyword, the CLI's flag, or
+the MCP tool argument. The same request therefore reads correctly whether it came
+from a library, a shell, or an agent over MCP, and an adapter never prints another
+surface's argument. Codes, `retryable` and `details` are identical across all
+three surfaces.
+
 ## Safety rules
 
 - **Confinement.** Relative paths resolve inside the workspace root. Absolute paths
@@ -435,8 +479,10 @@ Codes are stable; messages are not a contract.
   `*.key`, `id_rsa` and its siblings, `*.p12`, `*.pfx`, `authorized_keys`,
   `.netrc`, and anything under `.ssh/`, `.gnupg/` or `.aws/` fail with
   `SENSITIVE_PATH_REFUSED` (exit code 10). Override deliberately with
-  `--i-accept-secret-write-risk` (Core: `allow_sensitive_write=True`). The flag is
-  long because the mistake is expensive.
+  `--i-accept-secret-write-risk` on the CLI, `allow_sensitive_write=True` in Core,
+  or `i_accept_secret_write_risk` on the MCP tool. Each name is long because the
+  mistake is expensive. The error message names only the argument belonging to the
+  interface that received the request.
 - **Version-control-ignored targets warn.** Writing a path that git ignores still
   succeeds, but the result carries a warning that the change will not be committed.
 - **No shell.** Filekeeper never interpolates paths into a shell command.

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.7}/README.md

@@ -223,6 +223,13 @@ later file fails after earlier ones were written, the written files are rolled
 back to their pre-patch bytes and the failure names what was restored. A crash is
 resolved from the pending journal record, never from an all-or-nothing commit.
 
+When a hunk's header and its body disagree — the hunk is cut short or a line
+prefix is not ` `, `+` or `-` — the `PATCH_FAILED` error states the counts the
+header declares and the counts the body actually supplied, in the message and in
+`details.expected_old_lines`, `expected_new_lines`, `actual_old_lines` and
+`actual_new_lines`. The existing `line` and `reason` fields are still there. Patch
+text is never echoed into the error.
+
 ## Commands
 
 ```
@@ -283,10 +290,11 @@ affected path with the state the operation recorded:
 
 - if the path still matches the recorded **after** state, undo restores the
   recorded **before** bytes;
-- if it already matches the **before** state (a partially applied multi-file
-  operation), undo leaves it alone;
-- if it matches neither, someone changed it afterwards: the undo is refused with
-  `UNDO_CONFLICT` (exit code 12) and **nothing is modified**.
+- if it already matches the **before** state of an operation that never committed
+  (a partially applied multi-file operation), undo leaves it alone;
+- if a committed operation's path no longer matches the **after** state — edited,
+  deleted, or renamed away — the undo is refused with `UNDO_CONFLICT` (exit code
+  12) and **nothing is modified**.
 
 Undoing a create removes the file only while it still matches what was created.
 Undoing a delete restores the file only while the destination is still absent.
@@ -297,6 +305,18 @@ The undo is itself recorded as an operation, so `history list` remains a
 truthful ledger. **Redo is deferred** — it is not half-implemented; undoing an
 undo is the supported way to go forward again.
 
+A copy or a move records the path it read from in the operation's `metadata`
+under `source_path`, and its summary names both ends. `target_path` keeps its
+meaning — the path the operation targets — so existing readers are unaffected.
+
+A refused undo is recorded too: the ledger gains an `undo_refused` row with the
+target path, the conflict code, and the paths that blocked the undo. It changed
+nothing, so it carries no items, is never offered as undoable, and `undo-last`
+skips it. A refusal of a refusal is the one exception: undoing that
+`undo_refused` row is refused with the same coded error, but writes no second row,
+because the existing row already states the conflict. Every recorded path is
+workspace-relative, never a resolved host path.
+
 `keeper file read` writes file content to standard output unchanged (line endings
 included). Metadata goes to stderr, or into the JSON object with `--json`.
 `--input FILE` reads replacement content from a file, avoiding shell argument
@@ -359,6 +379,23 @@ re-reads the file and writes against its new hash.
 so its previous bytes were deliberately not stored; `history_skipped` then names
 the paths.
 
+**A dry run reports a preview, not a write.** With `"dry_run": true`, `changed` is
+`false`, `operation_id` and `after_hash` are `null`, and each item's `after_hash`
+and `size_bytes` are `null`: nothing was observed, so nothing is claimed. The hash
+a real run would produce appears as `predicted_after_hash` — a prediction, never an
+observation — and `would_change` says whether a real run would alter anything.
+`before_hash` and `preview_diff` are kept, because they describe the state the
+preview was computed against. The same shape applies to every mutating command and
+to the MCP tools that mirror them. A committed operation still reports
+`"changed": true` with its observed `after_hash`.
+
+`changed` and `would_change` answer different questions: `would_change` asks
+whether the bytes would differ, while `changed` records whether an operation
+executed and was journalled — so a real write of identical content reports
+`"changed": true` and adds a history row, which callers may rely on as proof a
+write completed. In a preview the two cannot disagree: when `would_change` is
+false, every item reports `"unchanged"`.
+
 Editing results add `match_stage` and `match_count` (text replacement),
 `preview_diff` (dry run), and, for patches, `patch_files` with per-hunk status.
 A failure that was rolled back reports the restored paths in the error details.
@@ -400,6 +437,13 @@ a shell predicate.
 
 Codes are stable; messages are not a contract.
 
+Messages name the interface the caller is using. A refusal that offers an
+override states that interface's own argument: Core's keyword, the CLI's flag, or
+the MCP tool argument. The same request therefore reads correctly whether it came
+from a library, a shell, or an agent over MCP, and an adapter never prints another
+surface's argument. Codes, `retryable` and `details` are identical across all
+three surfaces.
+
 ## Safety rules
 
 - **Confinement.** Relative paths resolve inside the workspace root. Absolute paths
@@ -414,8 +458,10 @@ Codes are stable; messages are not a contract.
   `*.key`, `id_rsa` and its siblings, `*.p12`, `*.pfx`, `authorized_keys`,
   `.netrc`, and anything under `.ssh/`, `.gnupg/` or `.aws/` fail with
   `SENSITIVE_PATH_REFUSED` (exit code 10). Override deliberately with
-  `--i-accept-secret-write-risk` (Core: `allow_sensitive_write=True`). The flag is
-  long because the mistake is expensive.
+  `--i-accept-secret-write-risk` on the CLI, `allow_sensitive_write=True` in Core,
+  or `i_accept_secret_write_risk` on the MCP tool. Each name is long because the
+  mistake is expensive. The error message names only the argument belonging to the
+  interface that received the request.
 - **Version-control-ignored targets warn.** Writing a path that git ignores still
   succeeds, but the result carries a warning that the change will not be committed.
 - **No shell.** Filekeeper never interpolates paths into a shell command.

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "filekeeper-cli"
-version = "0.1.4"
+version = "0.1.7"
 description = "Safe, predictable filesystem operations for humans and AI agents, with atomic writes and workspace confinement."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.7}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "filekeeper-cli"
-version = "0.1.4"
+version = "0.1.7"
 description = "Safe, predictable filesystem operations for humans and AI agents, with atomic writes and workspace confinement."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.7}/src/filekeeper/__init__.py

@@ -12,24 +12,28 @@ work; see ``CHANGELOG.md`` and ``README.md``.
 from __future__ import annotations
 
 from .core import (
+    CallerSurface,
     Config,
     ErrorCode,
     Filekeeper,
     FilekeeperError,
     FilekeeperService,
     MutationResult,
+    OverrideHint,
     Workspace,
 )
 
-__version__ = "0.1.4"
+__version__ = "0.1.7"
 
 __all__ = [
+    "CallerSurface",
     "Config",
     "ErrorCode",
     "Filekeeper",
     "FilekeeperError",
     "FilekeeperService",
     "MutationResult",
+    "OverrideHint",
     "Workspace",
     "__version__",
 ]

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.7}/src/filekeeper/cli/output.py

@@ -14,7 +14,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Any
 
-from ..core.errors import FilekeeperError
+from ..core.errors import CallerSurface, FilekeeperError
 from ..core.models import (
     ContentSearchResult,
     DirectoryListing,
@@ -53,6 +53,9 @@ def print_json(payload: dict[str, Any]) -> None:
 
 
 def print_error(error: FilekeeperError, *, as_json: bool) -> None:
+    """Render an error for this surface: its override hint names this CLI's flag."""
+
+    error = error.for_surface(CallerSurface.CLI)
     if as_json:
         print_json({"ok": False, "error": error.to_dict()})
         return
@@ -210,6 +213,15 @@ def history_show(record: OperationRecord) -> str:
             f"  {item.item_type:<9} {item.relative_path}  exists {exists}  "
             f"before {item.before_blob_hash or '-'}  after {item.after_blob_hash or '-'}"
         )
+    if record.metadata:
+        lines.append("metadata:")
+        for key in sorted(record.metadata):
+            value = record.metadata[key]
+            if isinstance(value, list):
+                rendered = ", ".join(str(entry) for entry in value)
+            else:
+                rendered = str(value)
+            lines.append(f"  {key}: {rendered}")
     if record.history_skipped:
         lines.append("history_skipped: " + ", ".join(record.history_skipped))
     return "\n".join(lines)

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.7}/src/filekeeper/core/__init__.py

@@ -5,7 +5,7 @@ the CLI, of the MCP server, or of any filesystem protocol.
 """
 
 from .config import Config
-from .errors import ErrorCode, FilekeeperError
+from .errors import CallerSurface, ErrorCode, FilekeeperError, OverrideHint
 from .history.blobs import BlobStore
 from .models import (
     ContentMatch,
@@ -27,6 +27,7 @@ from .workspace import WorkspaceHandle, WorkspaceRegistry
 
 __all__ = [
     "BlobStore",
+    "CallerSurface",
     "Config",
     "ContentMatch",
     "ContentSearchResult",
@@ -41,6 +42,7 @@ __all__ = [
     "FilekeeperService",
     "MutationResult",
     "OperationItemResult",
+    "OverrideHint",
     "PathInfo",
     "PathSearchResult",
     "ReadManyEntry",

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.7}/src/filekeeper/core/errors.py

@@ -7,6 +7,9 @@ error payloads, and callers may branch on the code without parsing prose.
 
 from __future__ import annotations
 
+import copy
+from collections.abc import Mapping
+from dataclasses import dataclass
 from enum import StrEnum
 from typing import Any
 
@@ -46,6 +49,38 @@ class ErrorCode(StrEnum):
     INTERNAL_ERROR = "INTERNAL_ERROR"
 
 
+class CallerSurface(StrEnum):
+    """The interface a caller reached Core through.
+
+    A refusal that offers an override must name the argument the caller actually
+    has. Core renders the sentence for ``CORE``; each adapter re-renders the same
+    error for its own surface before returning it, so no message ever names
+    another interface's argument.
+    """
+
+    CORE = "core"
+    CLI = "cli"
+    MCP = "mcp"
+
+
+@dataclass(frozen=True, slots=True)
+class OverrideHint:
+    """One "pass X to override" instruction, worded for each caller surface."""
+
+    sentences: Mapping[CallerSurface, str]
+
+    def sentence(self, surface: CallerSurface) -> str:
+        return self.sentences[surface]
+
+
+def override_hint(*, core: str, cli: str, mcp: str) -> OverrideHint:
+    """Build a hint whose sentence names each surface's own argument."""
+
+    return OverrideHint(
+        {CallerSurface.CORE: core, CallerSurface.CLI: cli, CallerSurface.MCP: mcp}
+    )
+
+
 class FilekeeperError(Exception):
     """Base error carrying a stable code, a human message, and optional details."""
 
@@ -59,6 +94,7 @@ class FilekeeperError(Exception):
         code: ErrorCode | None = None,
         retryable: bool | None = None,
         details: dict[str, Any] | None = None,
+        override_hint: OverrideHint | None = None,
     ) -> None:
         super().__init__(message)
         self.message = message
@@ -67,6 +103,27 @@ class FilekeeperError(Exception):
         if retryable is not None:
             self.retryable = retryable
         self.details: dict[str, Any] = details or {}
+        # Not serialised: the hint only lets an adapter re-word the message.
+        self.override_hint = override_hint
+
+    def for_surface(self, surface: CallerSurface) -> FilekeeperError:
+        """Return this error worded for the interface that received it.
+
+        ``code``, ``retryable`` and ``details`` are carried over untouched; only
+        the message's override sentence changes. An error with no hint, or a
+        request for the surface Core already rendered, is returned as is.
+        """
+
+        hint = self.override_hint
+        if hint is None or surface is CallerSurface.CORE:
+            return self
+        core_sentence = hint.sentence(CallerSurface.CORE)
+        if core_sentence not in self.message:
+            return self
+        adapted = copy.copy(self)
+        adapted.message = self.message.replace(core_sentence, hint.sentence(surface))
+        adapted.args = (adapted.message,)
+        return adapted
 
     def to_dict(self) -> dict[str, Any]:
         payload: dict[str, Any] = {
@@ -135,8 +192,14 @@ class SensitivePathRefusedError(FilekeeperError):
 
     code = ErrorCode.SENSITIVE_PATH_REFUSED
 
-    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
-        super().__init__(message, details=details)
+    def __init__(
+        self,
+        message: str,
+        *,
+        details: dict[str, Any] | None = None,
+        override_hint: OverrideHint | None = None,
+    ) -> None:
+        super().__init__(message, details=details, override_hint=override_hint)
 
 
 class AlreadyExistsError(FilekeeperError):

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.7}/src/filekeeper/core/history/journal.py

@@ -38,6 +38,9 @@ COMMITTED = "committed"
 UNDONE = "undone"
 FAILED = "failed"
 PARTIALLY_UNDONE = "partially_undone"
+# A refused undo is recorded so the ledger shows the attempt, but it is not a
+# mutation and is never offered as undoable.
+UNDO_REFUSED = "undo_refused"
 
 
 @dataclass(frozen=True, slots=True)
@@ -424,6 +427,7 @@ __all__ = [
     "PARTIALLY_UNDONE",
     "PENDING",
     "UNDONE",
+    "UNDO_REFUSED",
     "BeginResult",
     "OperationJournal",
     "PendingItem",

{filekeeper_cli-0.1.4 → filekeeper_cli-0.1.7}/src/filekeeper/core/history/undo.py

@@ -19,6 +19,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from ..errors import (
+    FilekeeperError,
     HistoryUnavailableError,
     StorageError,
     UndoConflictError,
@@ -27,7 +28,14 @@ from ..errors import (
 from ..models import MutationResult, OperationItemRecord, OperationItemResult, OperationRecord
 from ..safety.atomic import atomic_write_bytes, fsync_directory
 from ..safety.hashing import hash_file
-from .journal import COMMITTED, FAILED, UNDONE, OperationJournal, PendingItem
+from .journal import (
+    COMMITTED,
+    FAILED,
+    UNDO_REFUSED,
+    UNDONE,
+    OperationJournal,
+    PendingItem,
+)
 
 
 @dataclass(frozen=True, slots=True)
@@ -104,6 +112,13 @@ def _plan(journal: OperationJournal, record: OperationRecord) -> list[_Step]:
             conflicts.append(item.relative_path)
             continue
         if matches_before:
+            # A committed operation left every item in its post-operation state.
+            # Matching only the pre-operation state now means the path was
+            # changed or removed by someone else, not that this undo already
+            # ran. Only a failed operation can legitimately be part-way back.
+            if record.status == COMMITTED and not matches_after:
+                conflicts.append(item.relative_path)
+                continue
             already_before += 1
             continue
 
@@ -140,11 +155,13 @@ def _plan(journal: OperationJournal, record: OperationRecord) -> list[_Step]:
             conflicts.append(step.item.relative_path)
 
     if conflicts:
+        named = ", ".join(sorted(conflicts))
         raise UndoConflictError(
-            "cannot undo: these paths changed after the operation, so nothing was modified",
+            f"cannot undo: these paths changed after the operation ({named}), "
+            "so nothing was modified",
             details={
                 "operation_id": record.operation_id,
-                "conflicting_paths": ", ".join(sorted(conflicts)),
+                "conflicting_paths": named,
             },
         )
     if record.status == FAILED and already_before == len(record.items):
@@ -161,6 +178,16 @@ def _plan(journal: OperationJournal, record: OperationRecord) -> list[_Step]:
             "operation is not committed and cannot be undone",
             details={"operation_id": record.operation_id, "status": record.status},
         )
+    if not steps:
+        # Every item already holds its pre-operation state, which for a committed
+        # operation means the write left the content unchanged. There is nothing
+        # to restore, and reporting success would claim a change that never
+        # happened.
+        raise UndoConflictError(
+            "cannot undo: the operation left its target in the pre-operation state, "
+            "so undoing it would change nothing",
+            details={"operation_id": record.operation_id},
+        )
     return steps
 
 
@@ -272,6 +299,53 @@ def _result(
     )
 
 
+def _conflicting_paths(error: UndoConflictError) -> list[str]:
+    """The refusal's paths as a list, still caller-relative as Core recorded them."""
+
+    named = error.details.get("conflicting_paths")
+    if not isinstance(named, str):
+        return []
+    return sorted({part.strip() for part in named.split(",") if part.strip()})
+
+
+def _record_refusal(
+    journal: OperationJournal,
+    record: OperationRecord,
+    error: UndoConflictError,
+    *,
+    actor: str | None,
+    task_id: str | None,
+) -> str | None:
+    """Record a refused undo attempt so the ledger shows it was tried.
+
+    A refusal changes nothing, so the row carries no items and no before/after
+    hashes. Its status is ``failed`` — the attempt did not take effect — and its
+    type keeps it out of the undo stack (:func:`latest_undoable`). The conflict
+    code and the paths that blocked the undo travel in metadata. Recording is
+    best-effort: a storage failure here must never replace the refusal the
+    caller is owed.
+    """
+
+    try:
+        begun = journal.begin(
+            operation_type=UNDO_REFUSED,
+            target_path=record.target_path,
+            summary=f"Refused to undo operation {record.operation_id}: {error.message}",
+            items=[],
+            actor=actor,
+            task_id=task_id,
+            metadata={
+                "undone_operation": record.operation_id,
+                "conflict_code": str(error.code),
+                "conflicting_paths": _conflicting_paths(error),
+            },
+        )
+        journal.abort(begun.operation_id)
+    except FilekeeperError:
+        return None
+    return begun.operation_id
+
+
 def undo_operation(
     journal: OperationJournal,
     operation_id: str,
@@ -289,7 +363,16 @@ def undo_operation(
         raise OperationNotFoundError(
             "no operation with that id in this workspace", details={"operation_id": operation_id}
         )
-    steps = _plan(journal, record)
+    try:
+        steps = _plan(journal, record)
+    except UndoConflictError as exc:
+        # A refusal of another refusal adds nothing: the first row already
+        # records that this conflict was seen and nothing changed. Journalling
+        # the repeat would be noise, not new evidence, so only a refusal of a
+        # real operation is recorded.
+        if record.operation_type != UNDO_REFUSED:
+            _record_refusal(journal, record, exc, actor=actor, task_id=task_id)
+        raise
     undo_items = _undo_items(record)
 
     begun = journal.begin(
@@ -316,8 +399,14 @@ def undo_operation(
 
 
 def latest_undoable(journal: OperationJournal, *, actor: str | None = None) -> OperationRecord:
-    clauses = ["status IN (?, ?)"]
-    parameters: list[object] = [COMMITTED, FAILED]
+    """The most recent operation this workspace may undo.
+
+    A recorded refusal changed nothing; it is not a mutation and is never
+    offered as the next undo target, so ``undo-last`` skips those rows.
+    """
+
+    clauses = ["status IN (?, ?)", "operation_type != ?"]
+    parameters: list[object] = [COMMITTED, FAILED, UNDO_REFUSED]
     if actor is not None:
         clauses.append("actor = ?")
         parameters.append(actor)