postgres-aiops 0.4.0__tar.gz → 0.5.0__tar.gz

{postgres_aiops-0.4.0 → postgres_aiops-0.5.0}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.5.0 — 2026-07-20
+
+### Fixed
+- **`terminate_backend` / `cancel_query` refuse this tool's own backend**, and `update_setting` refuses the postmaster settings that would strand the undo at the next restart (`listen_addresses`, `port`, `max_connections`, `ssl`, `hba_file`, …).
+- A connection lost **mid-statement** now raises a dedicated error and is audited as `unknown`, not `error`..
+- Harness: a write whose response is lost is audited `status=unknown`, not `error` — it may have taken effect. Undo tokens gain `effectVerified` (undo.db migrated in place).
+- Harness: a dry-run no longer records an undo token, and no longer requires a named approver. Guards now run on the preview path.
+- Truncated strings end in an ellipsis instead of being cut silently; error messages are capped at 800 chars, not 300.
+
+See RELEASE_NOTES.md for the full detail.
+
 ## v0.3.0 — 2026-07-17
 
 ### Added

{postgres_aiops-0.4.0 → postgres_aiops-0.5.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: postgres-aiops
-Version: 0.4.0
+Version: 0.5.0
 Summary: Governed AI-ops for PostgreSQL DBA operations: slow-query RCA, bloat/vacuum & blocking-lock analysis with a built-in governance harness (audit, budget, undo, risk tiers)
-Author-email: wei <zhouwei008@gmail.com>
+Author-email: Wei Zhou <zhouwei008@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.11

postgres_aiops-0.5.0/RELEASE_NOTES.md

@@ -0,0 +1,50 @@
+# Release notes — postgres-aiops 0.5.0
+
+Previous release: 0.4.0.
+
+## In this tool
+
+- **`terminate_backend` / `cancel_query` refuse this tool's own backend**, and `update_setting` refuses the postmaster settings that would strand the undo at the next restart (`listen_addresses`, `port`, `max_connections`, `ssl`, `hba_file`, …). The read path already filtered `pg_backend_pid()`; the writes did not.
+- A connection lost **mid-statement** now raises a dedicated error and is audited as `unknown`, not `error`.
+
+## Every tool in the line: previews and undetermined outcomes
+
+This release fixes three harness defects that were silently degrading the audit
+trail and the undo store.
+
+**A write that loses its response is no longer recorded as a failure.** The
+harness assumed a sanitized error meant nothing had happened. That assumption is
+false in exactly the case that matters most: when a write severs its own
+connection, the request has already landed, the response cannot come back, and
+the operation was recorded as `status=error` with **no undo token created at
+all**. Transport-level failures are now audited as `status=unknown`, the result
+says plainly that the operation may have taken effect and should be verified
+before retrying, and a write that stashed its before-state has its inverse
+recorded anyway — flagged `effectVerified: false`, which `undo_list` and
+`undo_apply` both surface. Existing `undo.db` files are migrated in place; their
+rows read as verified, which is accurate, since the old code only ever recorded
+on the confirmed path.
+
+**A dry-run no longer writes an undo token.** Previews were recording inverses
+built from a before-state they never had: the undo callback's permissive default
+filled the gap with a guess, producing a real, applicable token for an operation
+that never happened.
+
+**A dry-run no longer demands a named approver.** Requiring an approval in order
+to ask whether something needs approval inverts what a preview is for. The tier
+is still computed and still audited, so the preview can tell you an approver
+will be needed; it just no longer refuses to answer. The write itself is gated
+exactly as before.
+
+The invariant, now stated: **a dry_run may read; it must never write.** Guards
+run on the preview path, which means a preview can and does report that an
+operation would be refused.
+
+## Also line-wide
+
+- **Truncated text now ends in an ellipsis** instead of being cut silently. This
+  line already treats a silent cut as a defect for lists; it was doing exactly
+  that to strings.
+- **Error messages are capped at 800 characters, not 300.** These messages end
+  with what to do instead, so the cap was removing the most useful sentence of
+  every long refusal.

{postgres_aiops-0.4.0 → postgres_aiops-0.5.0}/mcp_server/_shared.py

@@ -20,14 +20,30 @@ from typing import Any, Optional
 from mcp.server.fastmcp import FastMCP
 
 from postgres_aiops.config import load_config
-from postgres_aiops.connection import ConnectionManager, PgError
-from postgres_aiops.governance import sanitize
+from postgres_aiops.connection import ConnectionManager, PgConnectionLostError, PgError
+from postgres_aiops.governance import mark_unknown, sanitize
 
 logger = logging.getLogger(__name__)
 
 _DOCTOR_HINT = "Run 'postgres-aiops doctor' to verify connectivity and credentials."
 
 
+# Long enough to carry the remediation sentence. These messages teach the
+# caller what to do instead, and that clause comes last — a 300-char cap cut
+# it off silently on every refusal long enough to need one.
+_ERROR_MAX = 800
+
+
+# Failures that leave the statement's fate genuinely undetermined. Raised
+# only from the statement-executing path, so it means an ESTABLISHED link
+# died mid-statement — not that the server was unreachable. The driver gives
+# both the same class, so the connection layer discriminates by position and
+# raises a dedicated class; this layer only has to recognise it.
+# PostgreSQL rolls back on backend termination, so usually nothing landed —
+# but a COMMIT whose acknowledgement was lost did land.
+_UNDETERMINED_ERRORS = (PgConnectionLostError,)
+
+
 def _safe_error(exc: Exception, tool: str) -> str:
     """Return an agent-safe error string; log full detail server-side only."""
     logger.error("Tool %s failed", tool, exc_info=True)
@@ -41,7 +57,7 @@ def _safe_error(exc: Exception, tool: str) -> str:
         PgError,
     )
     if isinstance(exc, _passthrough):
-        return sanitize(str(exc), 300)
+        return sanitize(str(exc), _ERROR_MAX)
     return f"{type(exc).__name__}: operation failed."
 
 
@@ -65,7 +81,13 @@ def tool_errors(shape: str = "dict") -> Callable:
                     return [{"error": msg, "hint": _DOCTOR_HINT}]
                 if shape == "str":
                     return f"Error: {msg} {_DOCTOR_HINT}"
-                return {"error": msg, "hint": _DOCTOR_HINT}
+                payload = {"error": msg, "hint": _DOCTOR_HINT}
+                # Flatten the exception into a dict and its type is gone
+                # for good — so classify here, while it is still known,
+                # whether the operation may nonetheless have taken effect.
+                if isinstance(e, _UNDETERMINED_ERRORS):
+                    return mark_unknown(payload)
+                return payload
 
         return wrapper
 

{postgres_aiops-0.4.0 → postgres_aiops-0.5.0}/mcp_server/tools/remediation.py

@@ -73,12 +73,18 @@ def terminate_backend(pid: int, dry_run: bool = False, target: Optional[str] = N
     Captures the backend's pid + query for the audit trail; a terminate cannot be
     undone, so no undo is offered. Pass dry_run=True to preview.
 
+    Refuses this tool's own backend pid — including under dry_run, which must
+    report a refusal rather than preview a call that will be refused.
+
     Args:
         pid: Backend process id (from list_activity).
         dry_run: If True, preview without terminating.
         target: Target name from config; omit for the default.
     """
     conn = _get_connection(target)
+    # Ahead of the dry_run return: a preview whose real call would be refused
+    # must say so, or the caller reads the refusal as transient and retries.
+    ops.guard_terminate_backend(conn, pid, "terminate_backend")
     if dry_run:
         return {"dryRun": True, "wouldTerminate": {"pid": pid}}
     return ops.terminate_backend(conn, pid)
@@ -93,12 +99,16 @@ def cancel_query(pid: int, dry_run: bool = False, target: Optional[str] = None)
     Captures the backend's pid + query for audit; a cancel has no undo. Pass
     dry_run=True to preview.
 
+    Refuses this tool's own backend pid — the query it would cancel is this very
+    call. Enforced under dry_run too.
+
     Args:
         pid: Backend process id (from list_activity).
         dry_run: If True, preview without cancelling.
         target: Target name from config; omit for the default.
     """
     conn = _get_connection(target)
+    ops.guard_terminate_backend(conn, pid, "cancel_query")
     if dry_run:
         return {"dryRun": True, "wouldCancel": {"pid": pid}}
     return ops.cancel_query(conn, pid)
@@ -283,6 +293,11 @@ def update_setting(
     performed automatically. The prior value is captured so the harness records an
     undo that sets it back. Pass dry_run=True to preview.
 
+    Refuses the connection-affecting postmaster settings (listen_addresses,
+    port, max_connections, superuser_reserved_connections, ssl, hba_file):
+    nothing breaks now, but the operator's next restart applies them and strands
+    the undo. Enforced under dry_run too.
+
     Args:
         name: The configuration parameter name (e.g. work_mem).
         value: The new value (as a string).
@@ -290,6 +305,9 @@ def update_setting(
         target: Target name from config; omit for the default.
     """
     conn = _get_connection(target)
+    # Static denylist, so this costs nothing and cannot diverge from the real
+    # call — a preview of a refused setting must report the refusal.
+    ops.guard_update_setting(name)
     if dry_run:
         return {"dryRun": True, "wouldSet": {"name": name, "value": value}}
     return ops.update_setting(conn, name, value)

{postgres_aiops-0.4.0 → postgres_aiops-0.5.0}/mcp_server/tools/undo.py

@@ -36,6 +36,11 @@ def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
     Each entry names the original tool, the inverse tool that ``undo_apply``
     would run, and a human note. Use the ``undoId`` with ``undo_apply``.
 
+    Each entry carries ``effectVerified``. False means the original write
+    lost its response, so the change it reverses is PROBABLE, not confirmed —
+    check the live state before applying, and do not report the result as a
+    restore of a state that may never have been reached.
+
     Args:
         limit: Max rows to return (default 50).
         target: Unused (undo state is host-local); accepted for CLI uniformity.
@@ -52,6 +57,7 @@ def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
                 "originalTool": r["tool"],
                 "inverseTool": r["undo_tool"],
                 "note": r.get("note", ""),
+                "effectVerified": bool(r.get("effect_verified", 1)),
             }
             for r in rows
         ],
@@ -99,10 +105,12 @@ def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None
             f"Inverse tool '{inverse_tool}' is not registered on this server; cannot apply."
         )
 
+    effect_verified = bool(rec.get("effect_verified", 1))
     if dry_run:
         return {
             "dryRun": True,
             "undoId": undo_id,
+            "effectVerified": effect_verified,
             "wouldApply": {"tool": inverse_tool, "params": params},
         }
 
@@ -121,6 +129,15 @@ def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None
     return {
         "undoId": undo_id,
         "applied": applied,
+        "effectVerified": effect_verified,
         "inverseTool": inverse_tool,
         "result": result,
+        "note": (
+            ""
+            if effect_verified
+            else "The original write lost its response, so it was never confirmed "
+            "to have taken effect. This inverse ran regardless; report the "
+            "CURRENT server state, not a restore that may have had nothing "
+            "to restore."
+        ),
     }

{postgres_aiops-0.4.0 → postgres_aiops-0.5.0}/postgres_aiops/cli/_common.py

@@ -95,6 +95,28 @@ def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = No
     console.print("[magenta]  Run without --dry-run to execute.[/]\n")
 
 
+def dry_run_preview(
+    preview: Any, *, operation: str, api_call: str, parameters: dict | None = None
+) -> None:
+    """Render a GOVERNED dry-run result as the human-readable DRY-RUN banner.
+
+    ``preview`` must come from calling the governed tool with ``dry_run=True``,
+    so every guard it carries has already run against the real target. A refusal
+    arrives as ``{"error": ...}`` (``tool_errors`` flattens the exception) — it is
+    printed like any other CLI error and exits non-zero, exactly as the real
+    write would. Printing a green banner for a call that is about to be refused
+    is the preview being wrong, not merely incomplete.
+
+    On the allowed path the banner is byte-for-byte what it always was: routing
+    through the governed call buys the guard and the audit row, not a new
+    serialization.
+    """
+    if isinstance(preview, dict) and preview.get("error"):
+        console.print(f"[red]Error: {preview['error']}[/]")
+        raise typer.Exit(1)
+    dry_run_print(operation=operation, api_call=api_call, parameters=parameters)
+
+
 def double_confirm(action: str, resource: str) -> None:
     """Require two confirmations for a destructive operation."""
     console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")

{postgres_aiops-0.4.0 → postgres_aiops-0.5.0}/postgres_aiops/cli/remediate.py

@@ -13,6 +13,7 @@ from postgres_aiops.cli._common import (
     cli_errors,
     console,
     double_confirm,
+    dry_run_preview,
     dry_run_print,
 )
 
@@ -31,13 +32,17 @@ def remediate_terminate(
     dry_run: DryRunOption = False,
 ) -> None:
     """Terminate a backend (no undo; dry-run + confirm)."""
+    from mcp_server.tools import remediation as gov
+
     if dry_run:
-        dry_run_print(operation="terminate_backend",
-                      api_call="SELECT pg_terminate_backend(pid)", parameters={"pid": pid})
+        # Through the governed call: terminate_backend refuses this tool's own
+        # pid, so a preview must report that rather than a green banner.
+        dry_run_preview(
+            gov.terminate_backend(pid=pid, dry_run=True, target=target),
+            operation="terminate_backend",
+            api_call="SELECT pg_terminate_backend(pid)", parameters={"pid": pid})
         return
     double_confirm("terminate backend", str(pid))
-    from mcp_server.tools import remediation as gov
-
     console.print_json(json.dumps(gov.terminate_backend(pid=pid, target=target)))
 
 
@@ -49,13 +54,15 @@ def remediate_cancel(
     dry_run: DryRunOption = False,
 ) -> None:
     """Cancel a backend's running query (no undo; dry-run + confirm)."""
+    from mcp_server.tools import remediation as gov
+
     if dry_run:
-        dry_run_print(operation="cancel_query",
-                      api_call="SELECT pg_cancel_backend(pid)", parameters={"pid": pid})
+        dry_run_preview(
+            gov.cancel_query(pid=pid, dry_run=True, target=target),
+            operation="cancel_query",
+            api_call="SELECT pg_cancel_backend(pid)", parameters={"pid": pid})
         return
     double_confirm("cancel query on backend", str(pid))
-    from mcp_server.tools import remediation as gov
-
     console.print_json(json.dumps(gov.cancel_query(pid=pid, target=target)))
 
 
@@ -169,11 +176,15 @@ def remediate_set(
     dry_run: DryRunOption = False,
 ) -> None:
     """ALTER SYSTEM SET a parameter (reversible; dry-run + confirm)."""
+    from mcp_server.tools import remediation as gov
+
     if dry_run:
-        dry_run_print(operation="update_setting",
-                      api_call=f"ALTER SYSTEM SET {name} = ...", parameters={"value": value})
+        # Through the governed call: update_setting refuses the
+        # connection-affecting postmaster settings, so a preview must report it.
+        dry_run_preview(
+            gov.update_setting(name=name, value=value, dry_run=True, target=target),
+            operation="update_setting",
+            api_call=f"ALTER SYSTEM SET {name} = ...", parameters={"value": value})
         return
     double_confirm(f"ALTER SYSTEM SET {name} =", value)
-    from mcp_server.tools import remediation as gov
-
     console.print_json(json.dumps(gov.update_setting(name=name, value=value, target=target)))

{postgres_aiops-0.4.0 → postgres_aiops-0.5.0}/postgres_aiops/connection.py

@@ -41,6 +41,24 @@ class PgError(Exception):
         super().__init__(message)
 
 
+class PgConnectionLostError(PgError):
+    """An ESTABLISHED connection dropped while a statement was running.
+
+    Distinct from an ordinary failure because the outcome is genuinely
+    undetermined: the statement may have committed before the link died.
+    PostgreSQL rolls back on backend termination, so usually nothing landed —
+    but a COMMIT whose acknowledgement was lost did land, and from here the two
+    are indistinguishable. The MCP layer maps this to ``status=unknown`` rather
+    than asserting a failure it cannot vouch for.
+
+    Note the discriminator is WHERE it was raised, not the class or sqlstate:
+    psycopg reports both "could not connect" and "server closed the connection
+    unexpectedly" as ``OperationalError``, and a client-side detection of a
+    dropped link carries no sqlstate at all — so position is the only reliable
+    signal.
+    """
+
+
 def _teaching_message(exc: psycopg.Error, target: TargetConfig) -> str:
     """Map a psycopg error to an actionable, teaching message."""
     sqlstate = getattr(exc, "sqlstate", None)
@@ -124,7 +142,11 @@ class PgConnection:
                 cur.execute(sql, params)
                 return getattr(cur, "statusmessage", "") or "OK"
         except psycopg.Error as exc:
-            raise PgError(
+            # Reached only on an established connection, so an OperationalError
+            # here means the link died mid-statement — not that we failed to
+            # reach the server.
+            cls = PgConnectionLostError if isinstance(exc, psycopg.OperationalError) else PgError
+            raise cls(
                 _teaching_message(exc, self._target),
                 sqlstate=getattr(exc, "sqlstate", None),
             ) from exc

{postgres_aiops-0.4.0 → postgres_aiops-0.5.0}/postgres_aiops/governance/__init__.py

@@ -16,6 +16,12 @@ State lives under ``ops_home()`` (default ``~/.postgres-aiops``).
 from postgres_aiops.governance.audit import AuditEngine, get_engine
 from postgres_aiops.governance.budget import BudgetExceeded, BudgetTracker, get_budget
 from postgres_aiops.governance.decorators import PolicyDenied, governed_tool
+from postgres_aiops.governance.outcome import (
+    UNKNOWN_FIELD,
+    capture_prior_state,
+    is_unknown,
+    mark_unknown,
+)
 from postgres_aiops.governance.patterns import Pattern, PatternMatch, get_pattern_engine
 from postgres_aiops.governance.policy import TierDecision, get_policy_engine
 from postgres_aiops.governance.readonly import READ_ONLY_ENV, is_read_only
@@ -28,6 +34,10 @@ __all__ = [
     "opt_str",
     "is_read_only",
     "READ_ONLY_ENV",
+    "capture_prior_state",
+    "mark_unknown",
+    "is_unknown",
+    "UNKNOWN_FIELD",
     "PolicyDenied",
     "get_engine",
     "AuditEngine",

{postgres_aiops-0.4.0 → postgres_aiops-0.5.0}/postgres_aiops/governance/decorators.py

@@ -34,6 +34,11 @@ from typing import Any
 
 from postgres_aiops.governance.audit import detect_agent, get_engine
 from postgres_aiops.governance.budget import BudgetExceeded, get_budget
+from postgres_aiops.governance.outcome import (
+    clear_prior_state,
+    is_unknown,
+    take_prior_state,
+)
 from postgres_aiops.governance.patterns import PatternMatch, get_pattern_engine
 from postgres_aiops.governance.policy import PolicyResult, get_policy_engine
 from postgres_aiops.governance.readonly import is_read_only, read_only_denial
@@ -155,7 +160,7 @@ class _CallState:
         "skill", "tool_name", "agent", "start", "status", "result",
         "policy_result", "pattern_match", "audit", "policy",
         "safe_params", "env", "risk_level", "timeout_seconds",
-        "rationale", "approved_by", "risk_tier", "undo",
+        "rationale", "approved_by", "risk_tier", "undo", "dry_run",
     )
 
     def __init__(
@@ -169,6 +174,10 @@ class _CallState:
         timeout_seconds: int,
         undo: Any = None,
     ) -> None:
+        # A previous call on this thread/task may have captured before-state
+        # that its own wrapper never consumed (it raised past _annotate_result).
+        # Start clean so one call's prior state can never be recorded as another's.
+        clear_prior_state()
         self.undo = undo
         self.skill = _infer_skill(func)
         self.tool_name = func.__name__
@@ -187,6 +196,10 @@ class _CallState:
         # log and participate in env scoping (previously only kwargs did).
         params = _bind_params(signature, args, kwargs)
         self.safe_params = _redact(params, sensitive)
+        # Previews are governed like any other call — audited, policy-checked,
+        # budget-counted — but they change nothing, so two things must not apply
+        # to them: the named-approver gate, and undo recording.
+        self.dry_run = bool(params.get("dry_run", False))
         env = params.get("target", params.get("env", ""))
         self.env = str(env) if env else ""
 
@@ -269,7 +282,15 @@ def _pre_check(state: _CallState) -> None:
         params=state.safe_params,
     )
     state.risk_tier = tier.tier
-    if tier.requires_approver and not state.approved_by:
+    # A preview is not the operation. Requiring a named human approver before a
+    # caller may ask "would this even be permitted?" inverts what a preview is
+    # for — you would have to obtain the approval in order to learn whether the
+    # thing needs one, or would be refused outright. The tier is still computed
+    # and still audited, so the preview can TELL the caller an approver will be
+    # needed; it just does not demand one to answer. Deny rules, budget, the
+    # read-only switch and every self-lockout guard still apply, and the write
+    # itself is gated normally.
+    if tier.requires_approver and not state.approved_by and not state.dry_run:
         reason = (
             f"Operation '{state.tool_name}' on '{state.env or 'target'}' requires "
             f"'{tier.tier}' approval (rule: {tier.rule}) but no approver is recorded. "
@@ -322,17 +343,51 @@ def _annotate_result(state: _CallState, result: Any) -> Any:
 
 
 def _record_undo(state: _CallState, result: Any) -> None:
-    """Compute and persist the inverse descriptor for a successful write.
+    """Compute and persist the inverse descriptor for a write.
+
+    Two paths:
 
-    Best-effort: a broken undo callable or store must never fail the call.
-    Attaches ``_undo_id`` to dict results so the agent / pilot can reference it.
+    * **Confirmed** — the tool returned normally, so ``result`` carries the
+      before-state its undo callable needs. Recorded ``effect_verified=True``.
+    * **Undetermined** — the response was lost (see
+      :mod:`postgres_aiops.governance.outcome`). The change may be live, so an
+      inverse still matters, but ``result`` is only an error payload. An
+      inverse is recorded ONLY when the write explicitly stashed its
+      before-state via ``capture_prior_state``; synthesizing one from an
+      empty result would produce a *wrong* inverse, which is worse than none.
+
+    Best-effort throughout: a broken undo callable or store must never fail
+    the call. Attaches ``_undo_id`` to dict results for later reference.
     """
     if state.undo is None:
         return
-    if isinstance(result, dict) and result.get("error"):
-        return  # sanitized failure — no change happened, so no inverse to record
+    if state.dry_run:
+        # A preview changed nothing, so there is nothing to invert — and the
+        # descriptor it would produce is actively dangerous. An undo callable
+        # reads the before-state out of the result, and a preview has none, so
+        # permissive defaults (``(result.get("priorState") or {}).get("running",
+        # True)``) fill the gap with a guess. That yielded a REAL, applicable
+        # start_container token for a stop that never happened.
+        return
+
+    verified = True
+    undo_input = result
+    if is_unknown(result):
+        prior = take_prior_state()
+        if prior is None:
+            _log.warning(
+                "%s.%s outcome undetermined and no prior state captured — "
+                "no inverse recorded; the change may be live and unrecorded",
+                state.skill, state.tool_name,
+            )
+            return
+        verified = False
+        undo_input = {"priorState": prior, "outcomeUnknown": True}
+    elif isinstance(result, dict) and result.get("error"):
+        return  # definite failure — no change happened, so no inverse
+
     try:
-        descriptor = state.undo(state.safe_params, result)
+        descriptor = state.undo(state.safe_params, undo_input)
     except Exception:  # noqa: BLE001 — undo computation must not fail the call
         _log.warning("undo callable for %s.%s raised", state.skill, state.tool_name,
                      exc_info=True)
@@ -347,6 +402,7 @@ def _record_undo(state: _CallState, result: Any) -> None:
             tool=state.tool_name,
             undo_descriptor=descriptor,
             orig_params=state.safe_params,
+            effect_verified=verified,
         )
         if undo_id and isinstance(result, dict):
             result.setdefault("_undo_id", undo_id)
@@ -374,7 +430,7 @@ def _finalize(state: _CallState) -> None:
     # dicts BEFORE this harness sees them) must not be audited as success —
     # compliance exception reports are built from this status.
     if state.status == "ok" and isinstance(state.result, dict) and state.result.get("error"):
-        state.status = "error"
+        state.status = "unknown" if is_unknown(state.result) else "error"
 
     duration = int((time.time() - state.start) * 1000)
 

postgres_aiops-0.5.0/postgres_aiops/governance/outcome.py

@@ -0,0 +1,104 @@
+"""Tell "the write did not happen" apart from "we cannot tell whether it happened".
+
+A governed write that loses its response is not a failed write. The request may
+already have landed; the only thing that certainly failed is our knowledge of
+the outcome. The harness used to collapse both into ``status='error'`` with no
+undo token — and it did so precisely where the operation was most dangerous,
+because the two coincide:
+
+    a write whose target is the very thing serving this tool's API
+    → the change takes effect
+    → the response never comes back, because what would have sent it is gone
+    → sanitized to {"error": ...} → audited as a FAILURE → no inverse recorded
+
+The audit trail then reports that the destructive call failed while the change
+is live and unrecorded. For a line whose product is "governed and reversible",
+a row that confidently states the wrong outcome is worse than a missing one.
+
+Two primitives fix that:
+
+``mark_unknown`` / ``is_unknown``
+    The MCP layer's ``tool_errors`` classifies the exception it caught. Only
+    errors that leave the request's fate genuinely undetermined (a read
+    timeout, a half-closed socket, a protocol error mid-response) are marked.
+    A connect error or a pool timeout means the request never left, and an HTTP
+    status error means the server answered — both are ordinary failures and are
+    NOT marked. The distinction is per-tool knowledge, so each tool's
+    ``mcp_server/_shared.py`` owns the exception tuple; this module only carries
+    the marker.
+
+``capture_prior_state`` / ``take_prior_state``
+    An undo callable receives ``(params, result)``. When the write raises, the
+    before-state that was read moments earlier dies with the exception and no
+    inverse can be computed. A write that wants its undo to survive a lost
+    response stashes the before-state *before* issuing the mutating request::
+
+        before = conn.get(...)
+        capture_prior_state({"running": before["running"]})
+        conn.post(...)                      # may never return
+
+    The harness then records the inverse even on the unknown path, flagged
+    ``effect_verified=False`` so nobody mistakes it for a confirmed change.
+    Opt-in by design: fabricating a descriptor from an empty result would
+    produce a *wrong* inverse, which is worse than none.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Any
+
+# Public result field. Explicit rather than inferred: a caller must never have
+# to guess from the error text whether the operation may have taken effect.
+UNKNOWN_FIELD = "outcomeUnknown"
+
+_UNKNOWN_NOTE = (
+    "The request was sent but no usable response came back, so this operation "
+    "MAY have taken effect on the server. Verify the current state before "
+    "retrying — a blind retry could apply it twice."
+)
+
+# Set by a write immediately before it issues its mutating request; consumed by
+# the harness. A ContextVar (not a module global) so concurrent calls and async
+# tools never read each other's state.
+_prior_state: ContextVar[dict[str, Any] | None] = ContextVar(
+    "governed_prior_state", default=None
+)
+
+
+def mark_unknown(payload: dict[str, Any]) -> dict[str, Any]:
+    """Return a NEW error payload flagged as having an undetermined outcome."""
+    marked = dict(payload)
+    marked[UNKNOWN_FIELD] = True
+    marked["note"] = _UNKNOWN_NOTE
+    return marked
+
+
+def is_unknown(result: Any) -> bool:
+    """True when ``result`` is an error payload whose effect is undetermined."""
+    return isinstance(result, dict) and result.get(UNKNOWN_FIELD) is True
+
+
+def capture_prior_state(state: dict[str, Any]) -> None:
+    """Stash before-state so the inverse survives a lost response.
+
+    Call this AFTER reading the before-state and BEFORE issuing the mutating
+    request. Overwrites any previously captured state for this call.
+    """
+    _prior_state.set(dict(state))
+
+
+def take_prior_state() -> dict[str, Any] | None:
+    """Consume the captured before-state (harness-internal).
+
+    Consuming rather than peeking keeps one call's state from leaking into the
+    next on a reused thread or task.
+    """
+    state = _prior_state.get()
+    _prior_state.set(None)
+    return state
+
+
+def clear_prior_state() -> None:
+    """Drop any captured state. Called at the start of every governed call."""
+    _prior_state.set(None)