postgres-aiops 0.7.0__tar.gz → 0.9.0__tar.gz

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v0.9.0 — 2026-08-10
+
+### Fixed
+- **An undetermined outcome no longer exits as a plain failure.** A write whose response was lost carries *both* `error` and `outcomeUnknown`, and the harness deliberately judges unknown first when writing the audit row — the change may have taken effect, so a blind retry could apply it twice. The CLI guard judged `error` first, so the audit said "may have taken effect" while the exit status told a script it had not happened. The two layers now agree (exit 2, not 1), and a test pins the ordering so it cannot silently flip back.
+- **The CLI reported a refused or failed governed write as a success.** 10 write call sites printed the governed twin's payload and exited **0** whatever it said — and `@tool_errors` flattens every refusal, guard rejection and upstream failure into `{"error": ...}` rather than raising, so nothing downstream of a `&&` chain or a CI step could tell a blocked write from a landed one. The dry-run path already exited non-zero, which made the asymmetry worse: the preview was stricter than the write it previews. Results now route through a `checked()` helper — exit 1 on an error payload, exit 2 on an undetermined outcome, unchanged on success. This defect class had been fixed repo-by-repo several times and kept coming back; an audit across the whole line found it live in **18 of the 24 tools at once (87 call sites)**, so each tool now carries an invariant test that fails if any future CLI command prints a governed result without checking it.
+
+## v0.8.0 — 2026-08-03
+
+### Fixed
+- **`undo apply` replays against the target the original write ran on.** It dispatched the inverse against whatever target the *caller* named — in practice the config's first entry — while the write's own target sat unused in the undo record. On a multi-target config the inverse therefore ran against the wrong host; it only looks harmless because the resource usually is not there, but two hosts holding the same name and the inverse **succeeds on the wrong one, silently**. An explicitly named target still wins. Line-wide: all 24 copies had the identical defect. Caught live in container-host-aiops, where a stop recorded against a Podman target replayed against a Portainer one.
+- **Undoing an `ALTER SYSTEM SET` no longer leaves the parameter pinned.** The inverse wrote the prior *value* back with another `ALTER SYSTEM SET`, so a parameter that had **no** `postgresql.auto.conf` entry beforehand ended up with one. The number was right, but `postgresql.auto.conf` overrides `postgresql.conf`, so the "undo" silently shadowed the operator's config file from then on — a later edit there would have no effect. `update_setting` now records where the value came from (`pg_settings.sourcefile`), and the inverse is `ALTER SYSTEM RESET` unless the parameter was already carried by auto.conf. Live-verified on PostgreSQL 16.14 in both directions, checking `postgresql.auto.conf` itself after each undo.
+
+### Added
+- `update_setting(reset=True)` / `remediate set <name> --reset` — `ALTER SYSTEM RESET` a parameter, dropping its `postgresql.auto.conf` entry so `postgresql.conf` or the built-in default applies again. This is what the corrected undo replays.
+- `priorState` on a setting change now carries `source` and `pinnedInAutoConf`, so a caller can see whether a value was explicitly pinned or inherited.
+
 ## v0.7.0 — 2026-08-02
 
 ### Changed (BREAKING)

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: postgres-aiops
-Version: 0.7.0
+Version: 0.9.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 Zhou <zhouwei008@gmail.com>
 License-Expression: MIT

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/docs/VERIFICATION.md

@@ -103,8 +103,22 @@ are open — record them as gaps rather than silently passing.
 - [x] ✅ `postgres-aiops undo apply <id>` → replayed correctly and recreated the
       index from the captured definition. (A replay bug found in an earlier
       round was fixed and is now covered by a regression test.)
-- [ ] `remediate set <guc> <value>` then `undo apply` → the prior value restored
-      (**open gap** — `update_setting` was not exercised live).
+- [x] ✅ `remediate set <guc> <value>` then `undo apply` — **closed 2026-08-03,
+      and it found a bug.** Both directions were run against PostgreSQL 16.14
+      with `postgresql.auto.conf` inspected after each step:
+      - a parameter with **no** prior auto.conf entry (`source = default`) →
+        undo now issues `ALTER SYSTEM RESET` and the file is left clean. It
+        used to write the prior *value* back as a new entry: the number was
+        right, but auto.conf **overrides** postgresql.conf, so the "undo"
+        silently pinned a parameter that had been inherited, and any later edit
+        to postgresql.conf would have had no effect.
+      - a parameter that **was** already pinned (`ALTER SYSTEM SET work_mem =
+        '2MB'` first) → undo restores the value and keeps the entry.
+      The discriminator is `pg_settings.sourcefile`: `source` reads
+      `configuration file` for postgresql.conf *and* auto.conf alike, so only
+      the filename separates them. Note the pin is **latent** — until someone
+      runs `pg_reload_conf()`, `source` still reads `default`, so the damage is
+      invisible at the moment it is done.
 
 ### 5. Irreversible writes are honest about it
 - [x] ✅ `remediate vacuum <table> --analyze` → the dead tuples were actually

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/mcp_server/tools/remediation.py

@@ -50,12 +50,27 @@ def _drop_index_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
 def _update_setting_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
     if not isinstance(result, dict):
         return None
-    prior = (result.get("priorState") or {}).get("value")
-    if prior is None or prior == "":
+    prior = result.get("priorState") or {}
+    if not prior.get("pinnedInAutoConf"):
+        # The parameter had no postgresql.auto.conf entry, so putting the prior
+        # VALUE back would restore the number while leaving behind a pin that
+        # shadows postgresql.conf (auto.conf wins) for good. RESET removes the
+        # entry and lets the previous source apply again.
+        return {
+            "tool": "update_setting",
+            "params": {"name": params.get("name"), "reset": True},
+            "skill": "postgres-aiops",
+            "note": (
+                "Inverse of update_setting: ALTER SYSTEM RESET, because the "
+                "parameter had no postgresql.auto.conf entry beforehand."
+            ),
+        }
+    value = prior.get("value")
+    if value is None or value == "":
         return None
     return {
         "tool": "update_setting",
-        "params": {"name": params.get("name"), "value": prior},
+        "params": {"name": params.get("name"), "value": value},
         "skill": "postgres-aiops",
         "note": "Inverse of update_setting: ALTER SYSTEM SET back to the prior value.",
     }
@@ -282,16 +297,22 @@ def reindex(
 @tool_errors("dict")
 def update_setting(
     name: str,
-    value: str,
+    value: Optional[str] = None,
+    reset: bool = False,
     dry_run: bool = False,
     target: Optional[str] = None,
 ) -> dict:
-    """[WRITE][risk=medium] ALTER SYSTEM SET a parameter. Reversible: captures prior value.
+    """[WRITE][risk=medium] ALTER SYSTEM SET (or RESET) a parameter. Reversible.
 
     Writes postgresql.auto.conf; most parameters need SELECT pg_reload_conf() (or
     a restart for postmaster-context settings) to take effect — reported but NOT
-    performed automatically. The prior value is captured so the harness records an
-    undo that sets it back. Pass dry_run=True to preview.
+    performed automatically. The prior state is captured so the harness records
+    an undo. Pass dry_run=True to preview.
+
+    reset=True issues ALTER SYSTEM RESET, dropping the parameter's auto.conf
+    entry so postgresql.conf or the built-in default applies again. That is the
+    recorded inverse when the parameter had no auto.conf entry to begin with:
+    writing the prior value back would leave a pin that shadows postgresql.conf.
 
     Refuses the connection-affecting postmaster settings (listen_addresses,
     port, max_connections, superuser_reserved_connections, ssl, hba_file):
@@ -300,7 +321,8 @@ def update_setting(
 
     Args:
         name: The configuration parameter name (e.g. work_mem).
-        value: The new value (as a string).
+        value: The new value (as a string). Omit when reset=True.
+        reset: If True, ALTER SYSTEM RESET the parameter instead of setting it.
         dry_run: If True, preview without changing.
         target: Target name from config; omit for the default.
     """
@@ -309,5 +331,7 @@ def update_setting(
     # call — a preview of a refused setting must report the refusal.
     ops.guard_update_setting(name)
     if dry_run:
+        if reset:
+            return {"dryRun": True, "wouldReset": {"name": name}}
         return {"dryRun": True, "wouldSet": {"name": name, "value": value}}
-    return ops.update_setting(conn, name, value)
+    return ops.update_setting(conn, name, value, reset=reset)

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/mcp_server/tools/undo.py

@@ -80,6 +80,32 @@ def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
     }
 
 
+def _origin_target(rec: dict) -> Optional[str]:
+    """The target the ORIGINAL write ran against, read from its recorded params.
+
+    Without this the replay goes to whatever target the caller names — in
+    practice the config's first entry — so on a multi-target config the inverse
+    runs against the wrong host. It only *looks* harmless because the resource
+    usually does not exist there; when two hosts both hold a resource with the
+    same name the inverse succeeds on the wrong one, silently.
+
+    Caught live on 2026-08-03 in container-host-aiops: a ``stop_container``
+    recorded against a Podman target replayed against a Portainer target.
+
+    A ``target`` in ``orig_params`` also means the original call accepted one,
+    so the fallback cannot hand a keyword to a tool that has no such parameter.
+    """
+    raw = rec.get("orig_params") or ""
+    try:
+        orig = json.loads(raw) if raw else {}
+    except (ValueError, TypeError):
+        return None  # unreadable: fall back to the caller/default, as before
+    if not isinstance(orig, dict):
+        return None
+    value = orig.get("target")
+    return value if isinstance(value, str) and value else None
+
+
 @mcp.tool()
 @governed_tool(risk_level="medium")
 @tool_errors("dict")
@@ -143,8 +169,10 @@ def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None
         }
 
     call_params = dict(params)
-    if target is not None and "target" not in call_params:
-        call_params["target"] = target
+    if "target" not in call_params:
+        chosen = target if target is not None else _origin_target(rec)
+        if chosen is not None:
+            call_params["target"] = chosen
     result = fn(**call_params)
 
     # Only mark applied when the inverse did not itself return an error dict.

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/postgres_aiops/cli/_common.py

@@ -103,6 +103,53 @@ def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = No
     console.print("[magenta]  Run without --dry-run to execute.[/]\n")
 
 
+#: Exit status for a write whose outcome could not be determined. Kept distinct
+#: from 0 (confirmed) and 1 (failed) on purpose: a write whose response was lost
+#: is not a failure, but it is emphatically not a success either, and a script
+#: must be able to tell all three apart.
+EXIT_UNDETERMINED = 2
+
+
+def checked(result: Any) -> Any:
+    """Return ``result``, or abort when it reports a failed/undetermined write.
+
+    Every CLI command that calls a governed twin MUST pass the result through
+    here before printing its success line.
+
+    Governed twins are wrapped in ``@tool_errors``, which flattens any exception
+    into ``{"error": ...}`` and **returns** it. The CLI therefore never sees the
+    exception, so a command that prints its result unconditionally reports a
+    refused or failed operation exactly like a successful one — and exits 0, so
+    a script cannot tell either. The dry-run path already refused with a
+    non-zero status, which made the asymmetry worse: the preview was stricter
+    than the real call.
+
+    ``outcomeUnknown`` (set by the harness when a write's response is lost) is
+    neither success nor failure — the change may still have landed. It gets its
+    own line and :data:`EXIT_UNDETERMINED`, never a silent success.
+    """
+    if not isinstance(result, dict):
+        return result
+    error = result.get("error")
+    # ``outcomeUnknown`` is judged BEFORE ``error``, matching the harness: a
+    # write whose response was lost carries BOTH keys, and it is audited
+    # `unknown` precisely because it may have taken effect. Reporting that as a
+    # plain failure would tell a script the change did not happen and invite the
+    # double-apply the payload's own note warns about.
+    if result.get("outcomeUnknown"):
+        console.print(
+            f"[yellow]Outcome undetermined: {result.get('note') or ''}[/]"
+        )
+        raise typer.Exit(EXIT_UNDETERMINED)
+    if error:
+        console.print(f"[red]Error: {error}[/]")
+        hint = result.get("hint")
+        if hint:
+            console.print(f"[dim]{hint}[/]")
+        raise typer.Exit(1)
+    return result
+
+
 def dry_run_preview(
     preview: Any, *, operation: str, api_call: str, parameters: dict | None = None
 ) -> None:

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/postgres_aiops/cli/query.py

@@ -10,6 +10,7 @@ import typer
 from postgres_aiops.cli._common import (
     DryRunOption,
     TargetOption,
+    checked,
     cli_errors,
     console,
     double_confirm,
@@ -74,4 +75,4 @@ def query_reset(target: TargetOption = None, dry_run: DryRunOption = False) -> N
             operation="reset_query_stats", api_call="SELECT pg_stat_statements_reset()")
         return
     double_confirm("reset pg_stat_statements on", "this target")
-    console.print_json(json.dumps(gov.reset_query_stats(target=target)))
+    console.print_json(json.dumps(checked(gov.reset_query_stats(target=target))))

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/postgres_aiops/cli/remediate.py

@@ -10,6 +10,7 @@ import typer
 from postgres_aiops.cli._common import (
     DryRunOption,
     TargetOption,
+    checked,
     cli_errors,
     console,
     double_confirm,
@@ -42,7 +43,7 @@ def remediate_terminate(
             api_call="SELECT pg_terminate_backend(pid)", parameters={"pid": pid})
         return
     double_confirm("terminate backend", str(pid))
-    console.print_json(json.dumps(gov.terminate_backend(pid=pid, target=target)))
+    console.print_json(json.dumps(checked(gov.terminate_backend(pid=pid, target=target))))
 
 
 @remediate_app.command("cancel")
@@ -62,7 +63,7 @@ def remediate_cancel(
             api_call="SELECT pg_cancel_backend(pid)", parameters={"pid": pid})
         return
     double_confirm("cancel query on backend", str(pid))
-    console.print_json(json.dumps(gov.cancel_query(pid=pid, target=target)))
+    console.print_json(json.dumps(checked(gov.cancel_query(pid=pid, target=target))))
 
 
 @remediate_app.command("vacuum")
@@ -85,7 +86,7 @@ def remediate_vacuum(
         return
     double_confirm("VACUUM", table)
     console.print_json(
-        json.dumps(gov.run_vacuum(table=table, full=full, analyze=analyze, target=target)))
+        json.dumps(checked(gov.run_vacuum(table=table, full=full, analyze=analyze, target=target))))
 
 
 @remediate_app.command("analyze-table")
@@ -104,7 +105,7 @@ def remediate_analyze(
             operation="run_analyze", api_call=f"ANALYZE {table}")
         return
     double_confirm("ANALYZE", table)
-    console.print_json(json.dumps(gov.run_analyze(table=table, target=target)))
+    console.print_json(json.dumps(checked(gov.run_analyze(table=table, target=target))))
 
 
 @remediate_app.command("create-index")
@@ -131,8 +132,8 @@ def remediate_create_index(
             parameters={"columns": columns, "name": name, "unique": unique})
         return
     double_confirm("create index on", table)
-    result = gov.create_index(table=table, columns=columns, name=name, unique=unique,
-                              concurrently=concurrently, target=target)
+    result = checked(gov.create_index(table=table, columns=columns, name=name, unique=unique,
+                              concurrently=concurrently, target=target))
     console.print_json(json.dumps(result))
 
 
@@ -154,7 +155,7 @@ def remediate_drop_index(
         return
     double_confirm("drop index", name)
     console.print_json(
-        json.dumps(gov.drop_index(name=name, concurrently=concurrently, target=target)))
+        json.dumps(checked(gov.drop_index(name=name, concurrently=concurrently, target=target))))
 
 
 @remediate_app.command("reindex")
@@ -176,28 +177,37 @@ def remediate_reindex(
             operation="reindex", api_call=f"REINDEX {kind} {target_name}")
         return
     double_confirm(f"REINDEX {kind}", target_name)
-    console.print_json(json.dumps(gov.reindex(target_name=target_name, kind=kind,
-                                              concurrently=concurrently, target=target)))
+    console.print_json(json.dumps(checked(gov.reindex(target_name=target_name, kind=kind,
+                                              concurrently=concurrently, target=target))))
 
 
 @remediate_app.command("set")
 @cli_errors
 def remediate_set(
     name: Annotated[str, typer.Argument(help="Parameter name (e.g. work_mem)")],
-    value: Annotated[str, typer.Argument(help="New value")],
+    value: Annotated[str | None, typer.Argument(help="New value")] = None,
+    reset: Annotated[bool, typer.Option(
+        "--reset",
+        help="ALTER SYSTEM RESET instead: drop the parameter's "
+             "postgresql.auto.conf entry so postgresql.conf / the default applies",
+    )] = False,
     target: TargetOption = None,
     dry_run: DryRunOption = False,
 ) -> None:
-    """ALTER SYSTEM SET a parameter (reversible; dry-run + confirm)."""
+    """ALTER SYSTEM SET a parameter, or --reset it (reversible; dry-run + confirm)."""
     from mcp_server.tools import remediation as gov
 
+    action = f"ALTER SYSTEM RESET {name}" if reset else f"ALTER SYSTEM SET {name} ="
     if dry_run:
         # 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),
+            gov.update_setting(
+                name=name, value=value, reset=reset, dry_run=True, target=target),
             operation="update_setting",
-            api_call=f"ALTER SYSTEM SET {name} = ...", parameters={"value": value})
+            api_call=f"{action} ...",
+            parameters={"value": value, "reset": reset})
         return
-    double_confirm(f"ALTER SYSTEM SET {name} =", value)
-    console.print_json(json.dumps(gov.update_setting(name=name, value=value, target=target)))
+    double_confirm(action, "(default)" if reset else str(value))
+    console.print_json(json.dumps(
+        checked(gov.update_setting(name=name, value=value, reset=reset, target=target))))

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/postgres_aiops/cli/undo.py

@@ -15,6 +15,7 @@ import typer
 from postgres_aiops.cli._common import (
     DryRunOption,
     TargetOption,
+    checked,
     cli_errors,
     console,
     double_confirm,
@@ -65,4 +66,4 @@ def undo_apply_cmd(
         )
         return
     double_confirm("apply undo", undo_id)
-    console.print_json(json.dumps(gov.undo_apply(undo_id=undo_id, target=target)))
+    console.print_json(json.dumps(checked(gov.undo_apply(undo_id=undo_id, target=target))))

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/postgres_aiops/ops/remediation.py

@@ -338,13 +338,33 @@ def guard_update_setting(name: str) -> None:
     )
 
 
-def update_setting(conn: Any, name: str, value: str) -> dict:
-    """[WRITE] ALTER SYSTEM SET a parameter. Reversible: captures the prior value.
+def _pinned_in_auto_conf(prior: dict) -> bool:
+    """Was this parameter already carried by ``postgresql.auto.conf``?
+
+    ``pg_settings.source`` reads ``configuration file`` for both postgresql.conf
+    and postgresql.auto.conf, so only ``sourcefile`` separates them. A parameter
+    that has never been ALTER SYSTEM'd reads ``source = default`` with a NULL
+    sourcefile, or points at postgresql.conf. Verified on PostgreSQL 16.14.
+    """
+    sourcefile = prior.get("sourcefile") or ""
+    return str(sourcefile).endswith("postgresql.auto.conf")
+
+
+def update_setting(
+    conn: Any, name: str, value: str | None = None, reset: bool = False
+) -> dict:
+    """[WRITE] ALTER SYSTEM SET (or RESET) a parameter. Captures the prior state.
 
     Writes to postgresql.auto.conf; most parameters need ``SELECT pg_reload_conf()``
     (or a restart for ``pending_restart`` ones) to take effect — this is reported
     but NOT performed automatically.
 
+    ``reset=True`` issues ``ALTER SYSTEM RESET``, removing the parameter's
+    postgresql.auto.conf entry so whatever set it before (postgresql.conf, or the
+    built-in default) applies again. That is the correct inverse for a parameter
+    that had **no** auto.conf entry: writing the prior *value* back would restore
+    the number while leaving a pin that silently shadows postgresql.conf forever.
+
     **Refuses the connection-affecting postmaster settings**
     (``listen_addresses``, ``port``, ``max_connections``,
     ``superuser_reserved_connections``, ``ssl``, ``hba_file``). Those are the
@@ -353,22 +373,35 @@ def update_setting(conn: Any, name: str, value: str) -> dict:
     """
     guard_update_setting(name)
     setting_name = _validate_setting_name(name)
+    if not reset and value is None:
+        raise ValueError(
+            f"No value given for {setting_name!r}. Pass a value, or reset=True "
+            f"to drop its postgresql.auto.conf entry."
+        )
     prior = conn.query_one(
-        "SELECT setting, unit, context, pending_restart FROM pg_settings WHERE name = %(n)s",
+        "SELECT setting, unit, context, pending_restart, source, sourcefile "
+        "FROM pg_settings WHERE name = %(n)s",
         {"n": setting_name},
     ) or {}
-    literal = quote_literal(str(value))
-    sql = f"ALTER SYSTEM SET {setting_name} = {literal}"  # nosec B608 — name validated, value literal-quoted
+    if reset:
+        sql = f"ALTER SYSTEM RESET {setting_name}"  # nosec B608 — name validated
+    else:
+        literal = quote_literal(str(value))
+        sql = f"ALTER SYSTEM SET {setting_name} = {literal}"  # nosec B608 — name validated, value literal-quoted
     conn.execute(sql)
     needs_restart = bool(prior.get("pending_restart")) or prior.get("context") == "postmaster"
     return {
         "action": "update_setting",
         "setting": setting_name,
-        "newValue": str(value),
+        "newValue": None if reset else str(value),
+        "reset": reset,
         "priorState": {
             "value": s(prior.get("setting"), 256),
             "unit": opt(prior.get("unit"), 32),
             "context": s(prior.get("context"), 32),
+            # Where the value came from decides what "put it back" means.
+            "source": opt(prior.get("source"), 32),
+            "pinnedInAutoConf": _pinned_in_auto_conf(prior),
         },
         "reloadRequired": True,
         "restartRequired": needs_restart,

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "postgres-aiops"
-version = "0.7.0"
+version = "0.9.0"
 description = "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)"
 readme = "README.md"
 license = "MIT"

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/AIops-tools/Postgres-AIops",
     "source": "github"
   },
-  "version": "0.7.0",
+  "version": "0.9.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "postgres-aiops",
-      "version": "0.7.0",
+      "version": "0.9.0",
       "transport": {
         "type": "stdio"
       }

postgres_aiops-0.9.0/tests/test_cli_governed_exit.py

@@ -0,0 +1,167 @@
+"""The CLI must never report a failed governed write as a success.
+
+Two regressions are pinned here.
+
+**The behaviour** — ``checked()`` aborts non-zero on an error payload and on an
+undetermined outcome. Governed twins are wrapped in ``@tool_errors``, which
+flattens every exception into ``{"error": ...}`` and *returns* it, so a
+command that prints its result unconditionally exits 0 for an operation that
+was refused or failed.
+
+**The invariant** — every CLI call into a governed write twin routes its result
+through that helper. This is the part that matters over time: the defect was
+fixed repo-by-repo several times and kept coming back, because nothing stopped
+a *new* command from printing a governed result bare. A structural assertion
+does. It was introduced after an audit found the preview path guarded and the
+real write path unguarded in 18 of the 24 tools at once — the preview was
+stricter than the write it previews.
+"""
+
+from __future__ import annotations
+
+import ast
+import pathlib
+
+import pytest
+import typer
+
+from postgres_aiops.cli._common import checked
+
+CLI_DIR = pathlib.Path(__file__).resolve().parents[1] / "postgres_aiops" / "cli"
+TOOLS_DIR = pathlib.Path(__file__).resolve().parents[1] / "mcp_server" / "tools"
+
+#: Helpers that end the command non-zero when the payload reports a failure.
+CHECKERS = ['checked', 'dry_run_preview']
+
+
+@pytest.mark.unit
+def test_checked_aborts_on_error_payload():
+    with pytest.raises(typer.Exit) as exc:
+        checked({"error": "refused: that would lock this tool out"})
+    assert exc.value.exit_code == 1
+
+
+@pytest.mark.unit
+def test_checked_passes_a_successful_payload_through():
+    payload = {"action": "did_a_thing", "ok": True}
+    assert checked(payload) == payload
+
+
+def _callee(node: ast.AST) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return None
+
+
+def _write_tool_names() -> set[str]:
+    names: set[str] = set()
+    for path in TOOLS_DIR.glob("*.py"):
+        tree = ast.parse(path.read_text())
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef) and "[WRITE]" in (ast.get_docstring(node) or ""):
+                names.add(node.name)
+    return names
+
+
+def _aborts_on_failure(fn: ast.FunctionDef) -> bool:
+    """Does this function raise ``typer.Exit`` off a failure key in the payload?
+
+    Several commands guard with a locally named helper (``_require_ok``,
+    ``_emit``, ...) rather than the shared one. Those are correct guards, so the
+    invariant recognises the *shape* instead of a list of blessed names.
+    """
+    raises_exit = any(
+        isinstance(n, ast.Call) and _callee(n.func) == "Exit" for n in ast.walk(fn)
+    )
+    reads_failure_key = any(
+        isinstance(n, ast.Constant) and n.value in ("error", "outcomeUnknown")
+        for n in ast.walk(fn)
+    )
+    return raises_exit and reads_failure_key
+
+
+def _checker_names() -> set[str]:
+    """CHECKERS, every local guard, and any wrapper delegating to one of them."""
+    funcs: dict[str, list[ast.FunctionDef]] = {}
+    for path in CLI_DIR.rglob("*.py"):
+        for node in ast.walk(ast.parse(path.read_text())):
+            if isinstance(node, ast.FunctionDef):
+                funcs.setdefault(node.name, []).append(node)
+    found = set(CHECKERS) | {
+        name for name, defs in funcs.items() if any(_aborts_on_failure(f) for f in defs)
+    }
+    changed = True
+    while changed:
+        changed = False
+        for name, defs in funcs.items():
+            if name in found:
+                continue
+            for fn in defs:
+                if any(isinstance(n, ast.Call) and _callee(n.func) in found for n in ast.walk(fn)):
+                    found.add(name)
+                    changed = True
+                    break
+    return found
+
+
+@pytest.mark.unit
+def test_every_cli_governed_write_result_is_checked():
+    tools = _write_tool_names()
+    assert tools, "no [WRITE] tools parsed — the invariant would vacuously pass"
+    checkers = _checker_names()
+    unchecked: list[str] = []
+
+    for path in sorted(CLI_DIR.rglob("*.py")):
+        tree = ast.parse(path.read_text())
+        for func in [n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)]:
+            parents: dict[ast.AST, ast.AST] = {}
+            for node in ast.walk(func):
+                for child in ast.iter_child_nodes(node):
+                    parents[child] = node
+            guarded = {
+                arg.id
+                for node in ast.walk(func)
+                if isinstance(node, ast.Call) and _callee(node.func) in checkers
+                for arg in list(node.args) + [kw.value for kw in node.keywords]
+                if isinstance(arg, ast.Name)
+            }
+            for node in ast.walk(func):
+                if not (isinstance(node, ast.Call) and _callee(node.func) in tools):
+                    continue
+                parent = parents.get(node)
+                if isinstance(parent, (ast.keyword, ast.Starred)):
+                    parent = parents.get(parent)
+                if isinstance(parent, ast.Call) and _callee(parent.func) in checkers:
+                    continue
+                if isinstance(parent, ast.Assign) and any(
+                    isinstance(t, ast.Name) and t.id in guarded for t in parent.targets
+                ):
+                    continue
+                unchecked.append(f"{path.name}:{node.lineno}:{_callee(node.func)}")
+
+    assert not unchecked, (
+        "these CLI call sites print a governed write's result without routing it "
+        f"through {sorted(checkers)}, so a refusal exits 0: {unchecked}"
+    )
+
+@pytest.mark.unit
+def test_undetermined_outcome_beats_error_and_is_not_a_plain_failure():
+    """A lost response carries BOTH keys — it must exit 2, not 1.
+
+    ``@tool_errors`` flattens the exception into ``{"error": ...}`` and, when
+    the failure is one where the write may still have landed, also sets
+    ``outcomeUnknown``. The harness deliberately judges unknown *before* error
+    when writing the audit row, for the reason its own note gives: the change
+    may have taken effect, so a blind retry could apply it twice. The CLI has to
+    agree, or the audit says "may have taken effect" while the exit status tells
+    a script it did not happen.
+    """
+    with pytest.raises(typer.Exit) as exc:
+        checked({
+            "error": "connection reset while awaiting the response",
+            "outcomeUnknown": True,
+            "note": "may have taken effect",
+        })
+    assert exc.value.exit_code == 2

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/tests/test_mcp_tools.py

@@ -77,17 +77,48 @@ def test_drop_index_undo_none_without_definition():
 
 
 @pytest.mark.unit
-def test_update_setting_undo_sets_back_prior_value():
+def test_update_setting_undo_sets_back_prior_value_when_it_was_pinned():
+    """Only a parameter already carried by auto.conf is restored by value."""
     from mcp_server.tools.remediation import _update_setting_undo
 
-    desc = _update_setting_undo({"name": "work_mem"}, {"priorState": {"value": "4MB"}})
+    desc = _update_setting_undo(
+        {"name": "work_mem"},
+        {"priorState": {"value": "4MB", "source": "configuration file",
+                        "pinnedInAutoConf": True}},
+    )
     assert desc["tool"] == "update_setting"
     assert desc["params"] == {"name": "work_mem", "value": "4MB"}
 
 
 @pytest.mark.unit
-@pytest.mark.parametrize("result", [{"priorState": {"value": ""}}, {"priorState": {}}, "x"])
-def test_update_setting_undo_none_when_no_prior(result):
+def test_update_setting_undo_resets_when_there_was_no_auto_conf_entry():
+    """Restoring the VALUE would leave a pin that shadows postgresql.conf.
+
+    Shape from a live PostgreSQL 16.14: an untouched parameter reads
+    ``source = default`` with a NULL sourcefile, so the inverse of setting it
+    must be ALTER SYSTEM RESET, not ALTER SYSTEM SET back to the old number.
+    """
+    from mcp_server.tools.remediation import _update_setting_undo
+
+    desc = _update_setting_undo(
+        {"name": "work_mem"},
+        {"priorState": {"value": "4096", "unit": "kB", "context": "user",
+                        "source": "default", "pinnedInAutoConf": False}},
+    )
+    assert desc["params"] == {"name": "work_mem", "reset": True}
+    assert "RESET" in desc["note"]
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize(
+    "result",
+    [
+        {"priorState": {"value": "", "pinnedInAutoConf": True}},
+        {"priorState": {"pinnedInAutoConf": True}},
+        "x",
+    ],
+)
+def test_update_setting_undo_none_when_pinned_but_no_prior_value(result):
     from mcp_server.tools.remediation import _update_setting_undo
 
     assert _update_setting_undo({"name": "work_mem"}, result) is None

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/tests/test_undo_executor.py

@@ -21,18 +21,21 @@ from mcp_server.tools import undo as gov
 from postgres_aiops.governance import governed_tool
 
 _CALLS: list[dict] = []
+_TARGETS: list = []
 
 
 @governed_tool(risk_level="low")
 def _undo_probe(value: str = "", target=None) -> dict:
     """Synthetic inverse target used only by the undo-executor tests."""
     _CALLS.append({"value": value})
+    _TARGETS.append(target)
     return {"ok": True, "value": value}
 
 
 @pytest.fixture
 def gov_home(tmp_path, monkeypatch):
     _CALLS.clear()
+    _TARGETS.clear()
     # Register the probe only for the duration of these tests so it never
     # pollutes the real tool registry (which exact-count smoke tests assert on).
     mcp.add_tool(_undo_probe, name="_undo_probe")
@@ -77,6 +80,52 @@ def test_undo_apply_dispatches_inverse_and_marks_applied(gov_home):
     assert uid not in {u["undoId"] for u in gov.undo_list()["undos"]}
 
 
+@pytest.mark.unit
+def test_undo_apply_replays_against_the_target_the_write_ran_on(gov_home):
+    """A replay must go to the host the original write went to.
+
+    Without this the inverse ran against whatever target the caller named — in
+    practice the config's first entry — so on a multi-target config it hit the
+    wrong host. It only looked harmless because the resource usually does not
+    exist there; two hosts holding the same name and the inverse succeeds on the
+    wrong one, silently. Caught live on 2026-08-03 in container-host-aiops: a
+    stop recorded against a Podman target replayed against a Portainer target.
+    """
+    uid = undo_mod.get_undo_store().record(
+        skill="probe",
+        tool="orig_op",
+        undo_descriptor={"tool": "_undo_probe", "params": {"value": "v1"}},
+        orig_params={"value": "v1", "target": "second-host"},
+    )
+    result = gov.undo_apply(undo_id=uid)
+    assert result["applied"] is True
+    assert _TARGETS == ["second-host"]
+
+
+@pytest.mark.unit
+def test_undo_apply_prefers_an_explicit_caller_target(gov_home):
+    """An explicitly named target still wins — the fallback is only a default."""
+    uid = undo_mod.get_undo_store().record(
+        skill="probe",
+        tool="orig_op",
+        undo_descriptor={"tool": "_undo_probe", "params": {"value": "v1"}},
+        orig_params={"value": "v1", "target": "second-host"},
+    )
+    gov.undo_apply(undo_id=uid, target="chosen-host")
+    assert _TARGETS == ["chosen-host"]
+
+
+@pytest.mark.unit
+def test_undo_apply_survives_unreadable_orig_params(gov_home):
+    """Corrupt orig_params must not break the replay — just lose the fallback."""
+    uid = _record(params={"value": "v1"})
+    with sqlite3.connect(gov_home / "undo.db") as db:
+        db.execute("UPDATE undo_log SET orig_params = ? WHERE undo_id = ?",
+                   ("{not json", uid))
+    assert gov.undo_apply(undo_id=uid)["applied"] is True
+    assert _TARGETS == [None]
+
+
 @pytest.mark.unit
 def test_undo_apply_dry_run_previews_without_running(gov_home):
     uid = _record()

{postgres_aiops-0.7.0 → postgres_aiops-0.9.0}/uv.lock

@@ -492,7 +492,7 @@ wheels = [
 
 [[package]]
 name = "postgres-aiops"
-version = "0.7.0"
+version = "0.9.0"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },