healthcloud-cli 3.7.8__tar.gz → 3.7.9__tar.gz

{healthcloud_cli-3.7.8 → healthcloud_cli-3.7.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.7.8
+Version: 3.7.9
 Summary: Command-line interface for the HealthCloud MCP gateway, generated from the shared MCP tool manifest.
 Project-URL: Issues, https://github.com/healthcloudservices/healthcloud-services/issues
 Project-URL: Repository, https://github.com/healthcloudservices/healthcloud-services
@@ -529,14 +529,15 @@ and a missing `--agent-id` fails with one envelope on stderr and exit 1:
 ```
 
 Agent lifecycle changes are two first-class, send-once write commands. They
-require a saved `hc login` session (env-var credentials are not accepted for
-writes) and an explicit `--expected-config-version`, `--confirm` acknowledgement:
+require a saved `hc login` session (the command refuses before any request when
+none is saved; env-var credentials are not accepted here) and the `--confirm`
+acknowledgement. `--expected-config-version` is optional:
 
 ```bash
 uv run --frozen hc ams agents deactivate --environment dev --tenant-id TENANT_ID \
-  --agent-id AGENT_ID --expected-config-version N --confirm
+  --agent-id AGENT_ID [--expected-config-version N] --confirm
 uv run --frozen hc ams agents activate --environment dev --tenant-id TENANT_ID \
-  --agent-id AGENT_ID --expected-config-version N --confirm
+  --agent-id AGENT_ID [--expected-config-version N] --confirm
 ```
 
 Each command issues exactly one `GET /agents/{agent_id}`, local pre-checks,
@@ -566,9 +567,21 @@ explicitly that
 fields — a disabled agent can still be selected by those paths — and that
 in-flight runs, WSS sessions and schedules are untouched by this route.
 
+`data.config_version_check` says which concurrent-edit check actually ran:
+`matched` (the read `config_version` equals `--expected-config-version`),
+`not_run` (the flag was omitted, so **no** version check ran and the reviewed
+target plus `--confirm` are the approval), never a silent success. It is carried
+on the confirmed, refused **and** unknown envelopes alike, so an outcome where
+the write may already have committed still says which check ran. A deployment
+whose agent payload omits or nulls `config_version` cannot honour the flag: the
+command refuses that flag with a way forward (`Re-run without
+--expected-config-version`) instead of refusing every lifecycle command forever
+and instead of interpolating a Python `None` repr.
+
 Default `pretty` output prints those facts as labelled lines — `transition`,
-`requested`, `evidence` (`saved`, `side_effects`, `runtime`), `eligibility`,
-`mutation_replayed: false` — and closes with a `verification:` block, so a
+`requested`, `config_version_check`, `evidence` (`saved`, `side_effects`,
+`runtime`), `eligibility`, `mutation_replayed: false` — and closes with a
+`verification:` block, so a
 deactivate reads `transition: deactivate`, then
 `evidence: / saved: / status: confirmed`, then `verification: / saved_state:
 confirmed`, `side_effects: unverified`, `runtime: unverified`; it is never one
@@ -592,24 +605,45 @@ tenant, an already in-effect state, an unsupported `archived`/`draft` target
 (named as having no supported reversible transition here), or a
 `config_version` that no longer matches `--expected-config-version` — all of
 these are also enforced by the preview, which still sends nothing. A missing
-`--confirm` exits 2. That version check is a local best-effort
+`--confirm` exits 2. An `active` value the server emits as `1`/`0`/`"true"`/
+`"false"` is interpreted as a flag (an already in-effect state is still
+recognised and a correct write is still confirmed); any other value is
+unconfirmed, never a false success. That version check is a local best-effort
 guard only: the route has no `If-Match` and the server never compares the
 version, so it cannot prove atomicity and a request could still race between
 the read and the PUT.
 
-A transport error or `5xx` from the PUT is reported as `outcome: "unknown"`
-with `mutation_replayed: false`, `verification.saved_state: "unknown"` and a
+A transport error, a `5xx`/`408` from the PUT, or an interrupt (`Ctrl-C`) during
+the PUT or the readback is reported as `outcome: "unknown"` with
+`mutation_replayed: false`, `verification.saved_state: "unknown"` and a
 `reconciliation: {"status": "not_read", …}` block; the CLI sends no retry and
 does not re-read automatically — run `hc ams agents get` before doing anything
 else. A failed readback after an accepted PUT is reported the same way (unknown,
 not success). A `2xx` PUT answer whose body cannot be read as an agent object is
-also `outcome: "unknown"` (sent once, saved state unverified), never an internal
-error and never a success.
+also `outcome: "unknown"` (attempted once; the request may not have been sent
+and its saved state is unverified), never an internal error and never a
+success.
+
+A non-`5xx` rejection of the PUT (`409`, `422`, `400`, `403`, …) is worded as a
+**write** that the server refused, never as a read: `outcome: "failed"`,
+`verification.saved_state: "failed"`, `mutation_replayed: false`, the pre-write
+state under `data.evidence.saved.before`, and a `reconciliation` saying the CLI
+did not re-read. A `2xx` body that is not an agent object at all (for example a
+plain-text body) is a bounded `validation` refusal with the same
+`verification: not_applicable` as any read, never an `AttributeError` and never a
+traceback.
+
+The saved-session requirement above is enforced at the command boundary: the
+shared AMS authentication path still has the `HC_AMS_ADMIN_EMAIL`/
+`HC_AMS_ADMIN_PASSWORD` tenant-admin fallback that every AMS command group uses,
+so the guarantee is "these commands refuse without a saved session", not "no AMS
+write anywhere can reach the server on env-var credentials".
 
 Capability and organization assignments are one first-class, send-once write
-command. It requires a saved `hc login` session (env-var credentials are not
-accepted for writes), an explicit `--expected-config-version`, and the
-`--confirm` acknowledgement of the target and the printed reviewed diff:
+command. It requires a saved `hc login` session (the command refuses before any
+request when none is saved; env-var credentials are not accepted here), an
+explicit `--expected-config-version`, and the `--confirm` acknowledgement of the
+target and the printed reviewed diff:
 
 ```bash
 uv run --frozen hc ams agents assignments set --environment dev --tenant-id TENANT_ID \
@@ -706,8 +740,9 @@ carries a reference field is refused by field name by
 capabilities.
 
 Deleting an agent is one first-class, send-once destructive command. It requires
-a saved `hc login` session (env-var credentials are not accepted for writes) and
-the `--confirm` acknowledgement of the target and disclosure block it prints:
+a saved `hc login` session (the command refuses before any request when none is
+saved; env-var credentials are not accepted here) and the `--confirm`
+acknowledgement of the target and disclosure block it prints:
 
 ```bash
 uv run --frozen hc ams agents delete --environment dev --tenant-id TENANT_ID \

{healthcloud_cli-3.7.8 → healthcloud_cli-3.7.9}/README.md

@@ -511,14 +511,15 @@ and a missing `--agent-id` fails with one envelope on stderr and exit 1:
 ```
 
 Agent lifecycle changes are two first-class, send-once write commands. They
-require a saved `hc login` session (env-var credentials are not accepted for
-writes) and an explicit `--expected-config-version`, `--confirm` acknowledgement:
+require a saved `hc login` session (the command refuses before any request when
+none is saved; env-var credentials are not accepted here) and the `--confirm`
+acknowledgement. `--expected-config-version` is optional:
 
 ```bash
 uv run --frozen hc ams agents deactivate --environment dev --tenant-id TENANT_ID \
-  --agent-id AGENT_ID --expected-config-version N --confirm
+  --agent-id AGENT_ID [--expected-config-version N] --confirm
 uv run --frozen hc ams agents activate --environment dev --tenant-id TENANT_ID \
-  --agent-id AGENT_ID --expected-config-version N --confirm
+  --agent-id AGENT_ID [--expected-config-version N] --confirm
 ```
 
 Each command issues exactly one `GET /agents/{agent_id}`, local pre-checks,
@@ -548,9 +549,21 @@ explicitly that
 fields — a disabled agent can still be selected by those paths — and that
 in-flight runs, WSS sessions and schedules are untouched by this route.
 
+`data.config_version_check` says which concurrent-edit check actually ran:
+`matched` (the read `config_version` equals `--expected-config-version`),
+`not_run` (the flag was omitted, so **no** version check ran and the reviewed
+target plus `--confirm` are the approval), never a silent success. It is carried
+on the confirmed, refused **and** unknown envelopes alike, so an outcome where
+the write may already have committed still says which check ran. A deployment
+whose agent payload omits or nulls `config_version` cannot honour the flag: the
+command refuses that flag with a way forward (`Re-run without
+--expected-config-version`) instead of refusing every lifecycle command forever
+and instead of interpolating a Python `None` repr.
+
 Default `pretty` output prints those facts as labelled lines — `transition`,
-`requested`, `evidence` (`saved`, `side_effects`, `runtime`), `eligibility`,
-`mutation_replayed: false` — and closes with a `verification:` block, so a
+`requested`, `config_version_check`, `evidence` (`saved`, `side_effects`,
+`runtime`), `eligibility`, `mutation_replayed: false` — and closes with a
+`verification:` block, so a
 deactivate reads `transition: deactivate`, then
 `evidence: / saved: / status: confirmed`, then `verification: / saved_state:
 confirmed`, `side_effects: unverified`, `runtime: unverified`; it is never one
@@ -574,24 +587,45 @@ tenant, an already in-effect state, an unsupported `archived`/`draft` target
 (named as having no supported reversible transition here), or a
 `config_version` that no longer matches `--expected-config-version` — all of
 these are also enforced by the preview, which still sends nothing. A missing
-`--confirm` exits 2. That version check is a local best-effort
+`--confirm` exits 2. An `active` value the server emits as `1`/`0`/`"true"`/
+`"false"` is interpreted as a flag (an already in-effect state is still
+recognised and a correct write is still confirmed); any other value is
+unconfirmed, never a false success. That version check is a local best-effort
 guard only: the route has no `If-Match` and the server never compares the
 version, so it cannot prove atomicity and a request could still race between
 the read and the PUT.
 
-A transport error or `5xx` from the PUT is reported as `outcome: "unknown"`
-with `mutation_replayed: false`, `verification.saved_state: "unknown"` and a
+A transport error, a `5xx`/`408` from the PUT, or an interrupt (`Ctrl-C`) during
+the PUT or the readback is reported as `outcome: "unknown"` with
+`mutation_replayed: false`, `verification.saved_state: "unknown"` and a
 `reconciliation: {"status": "not_read", …}` block; the CLI sends no retry and
 does not re-read automatically — run `hc ams agents get` before doing anything
 else. A failed readback after an accepted PUT is reported the same way (unknown,
 not success). A `2xx` PUT answer whose body cannot be read as an agent object is
-also `outcome: "unknown"` (sent once, saved state unverified), never an internal
-error and never a success.
+also `outcome: "unknown"` (attempted once; the request may not have been sent
+and its saved state is unverified), never an internal error and never a
+success.
+
+A non-`5xx` rejection of the PUT (`409`, `422`, `400`, `403`, …) is worded as a
+**write** that the server refused, never as a read: `outcome: "failed"`,
+`verification.saved_state: "failed"`, `mutation_replayed: false`, the pre-write
+state under `data.evidence.saved.before`, and a `reconciliation` saying the CLI
+did not re-read. A `2xx` body that is not an agent object at all (for example a
+plain-text body) is a bounded `validation` refusal with the same
+`verification: not_applicable` as any read, never an `AttributeError` and never a
+traceback.
+
+The saved-session requirement above is enforced at the command boundary: the
+shared AMS authentication path still has the `HC_AMS_ADMIN_EMAIL`/
+`HC_AMS_ADMIN_PASSWORD` tenant-admin fallback that every AMS command group uses,
+so the guarantee is "these commands refuse without a saved session", not "no AMS
+write anywhere can reach the server on env-var credentials".
 
 Capability and organization assignments are one first-class, send-once write
-command. It requires a saved `hc login` session (env-var credentials are not
-accepted for writes), an explicit `--expected-config-version`, and the
-`--confirm` acknowledgement of the target and the printed reviewed diff:
+command. It requires a saved `hc login` session (the command refuses before any
+request when none is saved; env-var credentials are not accepted here), an
+explicit `--expected-config-version`, and the `--confirm` acknowledgement of the
+target and the printed reviewed diff:
 
 ```bash
 uv run --frozen hc ams agents assignments set --environment dev --tenant-id TENANT_ID \
@@ -688,8 +722,9 @@ carries a reference field is refused by field name by
 capabilities.
 
 Deleting an agent is one first-class, send-once destructive command. It requires
-a saved `hc login` session (env-var credentials are not accepted for writes) and
-the `--confirm` acknowledgement of the target and disclosure block it prints:
+a saved `hc login` session (the command refuses before any request when none is
+saved; env-var credentials are not accepted here) and the `--confirm`
+acknowledgement of the target and disclosure block it prints:
 
 ```bash
 uv run --frozen hc ams agents delete --environment dev --tenant-id TENANT_ID \

{healthcloud_cli-3.7.8 → healthcloud_cli-3.7.9}/healthcloud_cli/ams/agents/commands.py

@@ -93,10 +93,11 @@ def create_lifecycle_command(dependencies: AmsDependencies, transition: str) ->
     @_agent
     @click.option(
         "--expected-config-version",
-        required=True,
         type=int,
-        help="The config_version read before the write. A local best-effort guard only: the route has no "
-        "If-Match, so it never proves atomicity.",
+        default=None,
+        help="Optional: the config_version read before the write. A local best-effort guard only, because "
+        "the route has no If-Match. Omitting it runs no version check and says so in the envelope; a "
+        "deployment that reports no config_version refuses the flag rather than the whole command.",
     )
     @click.option(
         "--confirm",
@@ -111,7 +112,7 @@ def create_lifecycle_command(dependencies: AmsDependencies, transition: str) ->
         environment: str | None,
         tenant_id: str | None,
         agent_id: str,
-        expected_config_version: int,
+        expected_config_version: int | None,
         confirm: bool,
     ) -> None:
         target_data = {

{healthcloud_cli-3.7.8 → healthcloud_cli-3.7.9}/healthcloud_cli/ams/agents/operations.py

@@ -50,9 +50,32 @@ def list_agents(dependencies: AmsDependencies, target: TenantTarget) -> dict:
     )
 
 
+def _agent_object(value) -> bool:
+    """True only for a body that really is an agent object.
+
+    ``TypedClient.model`` returns a non-dict 200 body unchanged (``http.py``
+    hands back ``resp.text`` when JSON parsing fails), so an id/tenant check
+    written as ``value.id`` would crash with ``AttributeError`` and reach the
+    operator as a generic internal failure - after a committed write, in the
+    readback case. Every agent read and readback goes through this guard first.
+    """
+
+    return (
+        value is not None
+        and not isinstance(value, (str, bytes, bytearray, int, float, list, tuple, dict))
+        and getattr(value, "id", None) is not None
+        and getattr(value, "tenant_id", None) is not None
+    )
+
+
 def _verified_agent(sdk, target: TenantTarget, agent_id: str):
     agent = sdk.ams_admin.get_agent(agent_id)
-    if agent is None or agent.id != agent_id or agent.tenant_id != target.tenant_id:
+    if not _agent_object(agent):
+        raise AgentReadRefused(
+            "validation",
+            f"The server did not return an agent object for '{agent_id}'; stopped before reading or writing anything.",
+        )
+    if agent.id != agent_id or agent.tenant_id != target.tenant_id:
         raise AgentReadRefused("validation", "Agent/tenant identity mismatch; stopped.")
     return agent
 
@@ -110,10 +133,22 @@ UNKNOWN_LIFECYCLE_OUTCOME = (
     "`hc ams agents get` before doing anything else."
 )
 
-UNREADABLE_LIFECYCLE_RESPONSE = (
-    "The agent lifecycle write was sent once and the server answered, but its response could not be read "
-    "as an agent object, so the saved state is unknown. The mutation was not replayed. Re-read the agent "
-    "with `hc ams agents get` before doing anything else."
+# A TypeError (a drifted/local SDK fault around the call) and a ValueError (a 2xx
+# body that cannot be built into an agent) are indistinguishable at the call
+# site, so the message covers both honestly instead of claiming a send: the
+# request may never have left the process, and if it did, its outcome is
+# unknown.
+MAYBE_UNSENT_LIFECYCLE_OUTCOME = (
+    "The agent lifecycle write was attempted once and the installed SDK raised instead of returning a "
+    "readable agent response, so its outcome is unknown: the request may not have been sent, and if it "
+    "was, it may have been applied. The mutation was not replayed. Re-read the agent with "
+    "`hc ams agents get` before doing anything else."
+)
+
+INTERRUPTED_LIFECYCLE_OUTCOME = (
+    "The agent lifecycle write was interrupted after the request was attempted, so its outcome is unknown: "
+    "it may already have been applied. The mutation was not replayed. Re-read the agent with "
+    "`hc ams agents get` before doing anything else."
 )
 
 _RUNTIME_UNVERIFIED = (
@@ -152,7 +187,89 @@ def _state(agent) -> dict:
     }
 
 
-def _lifecycle_precheck(agent, agent_id: str, status: str, active: bool, expected_config_version: int) -> None:
+def _active_flag(value) -> bool | None:
+    """Interpret a server ``active`` value, or ``None`` when it is not a flag.
+
+    ``AgentConfig`` is a plain dataclass fed by ``json.loads``: a server that
+    emits ``1``/``0``/``"true"`` would make an identity check (``1 is True``)
+    false, so a correctly applied write would be reported "not confirmed" and the
+    already-in-effect precheck would not fire. Never a false success: only an
+    unambiguous flag maps, everything else stays unknown.
+    """
+
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int) and value in (0, 1):
+        return bool(value)
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in ("true", "1", "yes"):
+            return True
+        if lowered in ("false", "0", "no"):
+            return False
+    return None
+
+
+def _usable_config_version(value) -> bool:
+    """A ``config_version`` is only usable as a number; a bool, string or None is not.
+
+    ``AgentConfig`` is a plain dataclass fed by ``json.loads``, so a deployment can
+    legitimately emit ``"3"``. Nothing downstream may assume ``+ 1`` works on it.
+    """
+
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _config_version_check(agent, agent_id: str, expected_config_version: int | None) -> dict:
+    """Report which concurrency check actually ran, refusing a check that cannot.
+
+    ``--expected-config-version`` is a local best-effort guard the route cannot
+    honour (no If-Match). A deployment whose agent payload omits or nulls
+    ``config_version`` has no version to compare against, so asking for the check
+    is refused with a way forward - but omitting the flag is never a silent
+    success: the envelope says plainly that no version check ran.
+    """
+
+    observed = getattr(agent, "config_version", None)
+    usable = _usable_config_version(observed)
+    if expected_config_version is None:
+        return {
+            "status": "not_run",
+            "expected": None,
+            "observed": observed if usable else None,
+            "detail": (
+                "--expected-config-version was not passed, so no local concurrent-edit check ran. The "
+                "route has no If-Match and the server never compares a version; the reviewed target and "
+                "--confirm are the approval."
+            ),
+        }
+    if not usable:
+        raise AgentWriteRefused(
+            "validation",
+            f"Agent '{agent_id}' reports no usable config_version, so --expected-config-version cannot be "
+            "checked against it; nothing was sent. Re-run without --expected-config-version to send this "
+            "change with no local version check, or repair the agent's config_version first.",
+        )
+    if observed != expected_config_version:
+        raise AgentWriteRefused(
+            "validation",
+            f"--expected-config-version {expected_config_version} does not match the agent's config_version "
+            f"{observed}; a concurrent edit was refused locally and nothing was sent. This is a "
+            "best-effort local check because the route has no If-Match: the server never compares the "
+            "version, so a request could still race between a read and the write.",
+        )
+    return {
+        "status": "matched",
+        "expected": expected_config_version,
+        "observed": observed,
+        "detail": (
+            "The read config_version equals --expected-config-version. This is a best-effort local check "
+            "only: the route has no If-Match, so the server never compared it."
+        ),
+    }
+
+
+def _lifecycle_precheck(agent, agent_id: str, status: str, active: bool, expected_config_version: int | None) -> None:
     """Refuse locally, before the one write, when the transition is not valid."""
 
     if agent.status in ("archived", "draft"):
@@ -167,15 +284,8 @@ def _lifecycle_precheck(agent, agent_id: str, status: str, active: bool, expecte
             f"Agent '{agent_id}' reports an unsupported lifecycle status '{agent.status}'; only 'active' and "
             "'disabled' are written. Nothing was sent.",
         )
-    if agent.config_version != expected_config_version:
-        raise AgentWriteRefused(
-            "validation",
-            f"--expected-config-version {expected_config_version} does not match the agent's config_version "
-            f"{agent.config_version}; a concurrent edit was refused locally and nothing was sent. This is a "
-            "best-effort local check because the route has no If-Match: the server never compares the "
-            "version, so a request could still race between a read and the write.",
-        )
-    if agent.status == status and agent.active is active:
+    _config_version_check(agent, agent_id, expected_config_version)
+    if agent.status == status and _active_flag(agent.active) is active:
         raise AgentWriteRefused(
             "validation",
             f"Agent '{agent_id}' is already status '{status}' with active {str(active).lower()}; the change "
@@ -196,15 +306,23 @@ def _usable_readback(agent, agent_id: str, target: TenantTarget) -> bool:
         and getattr(agent, "id", None) == agent_id
         and getattr(agent, "tenant_id", None) == target.tenant_id
         and getattr(agent, "status", None) is not None
-        and getattr(agent, "active", None) is not None
+        and _active_flag(getattr(agent, "active", None)) is not None
     )
 
 
 def _lifecycle_evidence(before, after, status: str, active: bool, agent_id: str, target: TenantTarget) -> dict:
     identity = after is not None and after.id == agent_id and after.tenant_id == target.tenant_id
-    matched = identity and after.status == status and after.active is active
+    matched = identity and after.status == status and _active_flag(after.active) is active
+    # Making --expected-config-version optional removed the pre-write refusal that
+    # used to reject a non-int config_version, so this runs after the write: it must
+    # degrade to "not observed", never raise on a value it cannot add to.
+    before_version = getattr(before, "config_version", None)
+    after_version = None if after is None else getattr(after, "config_version", None)
     advanced = (
-        after is not None and before.config_version is not None and after.config_version == before.config_version + 1
+        after is not None
+        and _usable_config_version(before_version)
+        and _usable_config_version(after_version)
+        and after_version == before_version + 1
     )
     if matched:
         detail = "The readback shows exactly the status/active pair that was sent for this agent in this tenant."
@@ -259,7 +377,14 @@ def _eligibility(after) -> dict:
 
 
 def _lifecycle_envelope(
-    target: TenantTarget, agent_id: str, transition: str, status: str, active: bool, before, after
+    target: TenantTarget,
+    agent_id: str,
+    transition: str,
+    status: str,
+    active: bool,
+    before,
+    after,
+    version_check: dict,
 ) -> dict:
     envelope = succeeded(
         f"agents.{transition}",
@@ -267,6 +392,7 @@ def _lifecycle_envelope(
         {
             "transition": transition,
             "requested": {"status": status, "active": active},
+            "config_version_check": version_check,
             "evidence": _lifecycle_evidence(before, after, status, active, agent_id, target),
             "eligibility": _eligibility(after),
             "mutation_replayed": False,
@@ -281,17 +407,89 @@ def _lifecycle_envelope(
     return envelope
 
 
+def _rejected_lifecycle(
+    operation: str,
+    target: TenantTarget,
+    agent_id: str,
+    status: str,
+    active: bool,
+    before,
+    version_check: dict,
+    http_status: int,
+) -> None:
+    """Report a write the server refused: sent once, definitively not saved.
+
+    The request left the process, so the outcome must not be described as a read
+    ("read conflicted") and the verification block must not claim
+    ``not_applicable``: the server answered, so ``saved_state`` is ``failed``.
+    """
+
+    from ..errors import http_category
+
+    category = http_category(operation, http_status)
+    message = (
+        f"Agent '{agent_id}' lifecycle write was sent once and the server refused it with HTTP {http_status}; "
+        "nothing was written, nothing was replayed and no readback was taken. Review the agent with "
+        "`hc ams agents get` before retrying."
+    )
+    envelope = succeeded(
+        operation,
+        _lifecycle_target(target, agent_id),
+        {
+            "transition": operation.split(".", 1)[-1],
+            "requested": {"status": status, "active": active},
+            "config_version_check": version_check,
+            "mutation_replayed": False,
+            "reconciliation": {
+                "status": "not_read",
+                "detail": (
+                    "The server refused the write, so this command did not re-read the agent. Re-read with "
+                    "`hc ams agents get` before doing anything else."
+                ),
+            },
+            "evidence": {
+                "saved": {
+                    "status": "failed",
+                    "agent_id": agent_id,
+                    "detail": (
+                        "The server refused the lifecycle write, so the requested status/active pair is "
+                        "not saved. The state below was read before the write was sent."
+                    ),
+                    "before": _state(before),
+                },
+                "side_effects": {"status": "unverified", "detail": _SIDE_EFFECTS_UNVERIFIED},
+                "runtime": {"status": "unverified", "detail": _RUNTIME_UNVERIFIED},
+            },
+        },
+        read_only=False,
+    )
+    envelope["outcome"] = "failed"
+    envelope["error"] = {"category": category, "message": message}
+    envelope["verification"] = {
+        "saved_state": "failed",
+        "side_effects": "unverified",
+        "runtime": "unverified",
+    }
+    raise DomainOutcomeFailed(category, message, envelope)
+
+
 def _unknown_lifecycle(
     operation: str,
     target: TenantTarget,
     agent_id: str,
     status: str,
     active: bool,
+    version_check: dict,
     *,
     reconciliation_detail: str,
     message: str = UNKNOWN_LIFECYCLE_OUTCOME,
 ) -> None:
-    """Report an uncertain send once, without replaying or re-reading it."""
+    """Report an uncertain send once, without replaying or re-reading it.
+
+    ``version_check`` is carried on this envelope too: the write may have
+    committed, so which concurrent-edit check actually ran is exactly what the
+    operator needs while deciding whether a second edit could have been in play.
+    """
 
     envelope = unknown(
         operation,
@@ -302,6 +500,7 @@ def _unknown_lifecycle(
             "mutation_replayed": False,
             "requested": {"status": status, "active": active},
             "reconciliation": {"status": "not_read", "detail": reconciliation_detail},
+            "config_version_check": version_check,
         },
         read_only=False,
     )
@@ -319,27 +518,47 @@ def set_lifecycle(
     agent_id: str,
     *,
     transition: Literal["activate", "deactivate"],
-    expected_config_version: int,
+    expected_config_version: int | None,
 ) -> dict:
     """Change one agent's lifecycle availability once, then read it back.
 
     Sequence: exactly one ``GET /agents/{agent_id}``, local pre-checks, exactly
     one ``PUT /agents/{agent_id}`` whose body is only ``status``+``active``, then
     exactly one ``GET`` readback. There is never a retry, a replay, a second
-    write or a generic update fallback. ``--expected-config-version`` is a local
-    best-effort guard only: the route has no version/If-Match check.
+    write or a generic update fallback. ``--expected-config-version`` is an
+    optional local best-effort guard: the route has no version/If-Match check,
+    and omitting the flag is reported as ``config_version_check: not_run`` rather
+    than pretending a check happened.
     """
 
     from healthcloud.errors import HealthCloudHTTPError, HealthCloudNetworkError
 
+    from ..results import is_unknown_write_status
+
     agent_id = _agent_id(agent_id)
     status, active = _lifecycle_write_pair(transition)
     operation = f"agents.{transition}"
     with dependencies.authenticated_sdk_factory(target) as sdk:
         before = _verified_agent(sdk, target, agent_id)
         _lifecycle_precheck(before, agent_id, status, active, expected_config_version)
+        version_check = _config_version_check(before, agent_id, expected_config_version)
         try:
             sdk.ams_admin.set_agent_lifecycle(agent_id, status=status, active=active)
+        except KeyboardInterrupt:
+            # BaseException: every ordinary handler above is bypassed, and the
+            # write may already have committed. Report the uncertain outcome
+            # instead of a plain transport failure that claims nothing was sent.
+            _unknown_lifecycle(
+                operation,
+                target,
+                agent_id,
+                status,
+                active,
+                version_check,
+                message=INTERRUPTED_LIFECYCLE_OUTCOME,
+                reconciliation_detail="The command was interrupted after the write was attempted and did not "
+                "re-read the agent; run `hc ams agents get` before doing anything else.",
+            )
         except HealthCloudNetworkError:
             _unknown_lifecycle(
                 operation,
@@ -347,38 +566,56 @@ def set_lifecycle(
                 agent_id,
                 status,
                 active,
+                version_check,
                 reconciliation_detail="This command did not re-read the agent after the uncertain write; "
                 "run `hc ams agents get` before doing anything else.",
             )
         except HealthCloudHTTPError as error:
-            if 500 <= (getattr(error, "status_code", 0) or 0) < 600:
+            http_status = getattr(error, "status_code", None)
+            # No usable status is itself an uncertain answer for a sent write.
+            if not isinstance(http_status, int) or is_unknown_write_status(http_status):
                 _unknown_lifecycle(
                     operation,
                     target,
                     agent_id,
                     status,
                     active,
+                    version_check,
                     reconciliation_detail="This command did not re-read the agent after the uncertain write; "
                     "run `hc ams agents get` before doing anything else.",
                 )
-            raise
+            # A non-5xx answer is a definite refusal of a request that was sent:
+            # never described as a read, and never ``saved_state: not_applicable``.
+            _rejected_lifecycle(operation, target, agent_id, status, active, before, version_check, http_status)
         except TypeError, ValueError:
-            # The PUT was answered 2xx, but the body could not be built into an
-            # agent (a partial object or an unexpected shape). The write was
-            # sent exactly once, so this is an unknown outcome, never a crash
-            # and never a success.
+            # Either the PUT was answered 2xx and the body could not be built
+            # into an agent, or a drifted SDK raised around the call. Both were
+            # attempted once, neither is a crash and neither is a success.
             _unknown_lifecycle(
                 operation,
                 target,
                 agent_id,
                 status,
                 active,
-                message=UNREADABLE_LIFECYCLE_RESPONSE,
-                reconciliation_detail="This command did not re-read the agent after the uncertain write; "
-                "run `hc ams agents get` before doing anything else.",
+                version_check,
+                message=MAYBE_UNSENT_LIFECYCLE_OUTCOME,
+                reconciliation_detail="The SDK did not report a readable response, so the request may not "
+                "have been sent. Re-read with `hc ams agents get` before doing anything else.",
             )
         try:
             after = sdk.ams_admin.get_agent(agent_id)
+        except KeyboardInterrupt:
+            _unknown_lifecycle(
+                operation,
+                target,
+                agent_id,
+                status,
+                active,
+                version_check,
+                message=INTERRUPTED_LIFECYCLE_OUTCOME,
+                reconciliation_detail="The write was accepted, but the command was interrupted during the "
+                "readback; run `hc ams agents get` before doing anything else.",
+            )
         except TypeError, ValueError:
             # An accepted write with an unreadable readback is unconfirmed
             # evidence, not an internal error and not a replay: fall through to
@@ -391,12 +628,13 @@ def set_lifecycle(
                 agent_id,
                 status,
                 active,
+                version_check,
                 reconciliation_detail="The write was accepted, but the readback could not be read. The saved "
                 "state is unverified; run `hc ams agents get` before doing anything else.",
             )
         if not _usable_readback(after, agent_id, target):
             after = None
-        envelope = _lifecycle_envelope(target, agent_id, transition, status, active, before, after)
+        envelope = _lifecycle_envelope(target, agent_id, transition, status, active, before, after, version_check)
         if envelope["data"]["evidence"]["saved"]["status"] == "confirmed":
             return envelope
         if after is None:
@@ -1118,7 +1356,7 @@ def preview_lifecycle(
     agent_id: str,
     *,
     transition: Literal["activate", "deactivate"],
-    expected_config_version: int,
+    expected_config_version: int | None,
 ) -> None:
     """Print the exact lifecycle change without sending it.
 

{healthcloud_cli-3.7.8 → healthcloud_cli-3.7.9}/healthcloud_cli/ams/context.py

@@ -103,6 +103,75 @@ def preflight_discovery(invocation: AmsContext) -> None:
         raise click.ClickException("Discover requires explicit environment/tenant flags, without a target file.")
 
 
+# The exact call this CLI makes on each ``ams_admin`` agent method: positional
+# argument count plus the keyword names it passes. A callable check alone is not
+# enough: an installed SDK whose signature drifted raises ``TypeError`` before any
+# bytes leave the process, which a sent-once write must never report as "may have
+# committed". Refusing the drifted signature here keeps that impossible.
+_AGENT_METHOD_CALLS = {
+    "get_agent": (1, ()),
+    "delete_agent": (1, ()),
+    "set_agent_lifecycle": (1, ("status", "active")),
+    "set_agent_assignments": (
+        1,
+        (
+            "department_id",
+            "team_id",
+            "skill_ids",
+            "tool_ids",
+            "policy_ids",
+            "guardrail_ids",
+            "data_source_ids",
+        ),
+    ),
+}
+
+
+def _signature_binds(method, positional: int, keywords: tuple[str, ...]) -> bool:
+    """True when ``method`` accepts this CLI's call; un-introspectable is allowed."""
+
+    import inspect
+
+    try:
+        params = list(inspect.signature(method).parameters.values())
+    except TypeError, ValueError:
+        # A C callable or a stub tells us nothing; the call site keeps its own guard.
+        return True
+    var_keyword = any(param.kind is inspect.Parameter.VAR_KEYWORD for param in params)
+    var_positional = any(param.kind is inspect.Parameter.VAR_POSITIONAL for param in params)
+    named = {param.name: param for param in params}
+    for keyword in keywords:
+        param = named.get(keyword)
+        if param is not None and param.kind is inspect.Parameter.POSITIONAL_ONLY:
+            return False
+        if param is None and not var_keyword:
+            return False
+    positional_params = [
+        param
+        for param in params
+        if param.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+    ]
+    if not var_positional and positional > len(positional_params):
+        return False
+    # A required POSITIONAL_OR_KEYWORD parameter the CLI passes by name is covered by
+    # ``keywords``, so it must not also be counted against the positional budget.
+    required_positional = [
+        param
+        for param in positional_params
+        if param.default is inspect.Parameter.empty
+        and not (param.kind is inspect.Parameter.POSITIONAL_OR_KEYWORD and param.name in keywords)
+    ]
+    if len(required_positional) > positional:
+        return False
+    required_keyword_only = [
+        param
+        for param in params
+        if param.kind is inspect.Parameter.KEYWORD_ONLY and param.default is inspect.Parameter.empty
+    ]
+    kwargs_covered = var_keyword or all(param.name in keywords for param in required_keyword_only)
+    return kwargs_covered
+
+
 def preflight_agents(
     invocation: AmsContext,
     target: TenantTarget | None = None,
@@ -131,6 +200,13 @@ def preflight_agents(
             raise click.ClickException(
                 "SDK missing ams_admin agent lifecycle support; use the reviewed SDK version required by this CLI."
             )
+        for method in methods:
+            call = _AGENT_METHOD_CALLS.get(method)
+            if call is not None and not _signature_binds(getattr(admin, method), *call):
+                raise click.ClickException(
+                    f"Installed SDK ams_admin {method} does not accept the call this CLI makes; use the "
+                    "reviewed SDK version required by this CLI. Nothing was sent."
+                )
     finally:
         sdk.close()
 

{healthcloud_cli-3.7.8 → healthcloud_cli-3.7.9}/healthcloud_cli/ams/errors.py

@@ -12,7 +12,7 @@ from pydantic import ValidationError
 
 from ..output import output_mode
 from .domain_errors import DomainReadRefused
-from .pretty import error_line, success_text, unknown_details
+from .pretty import error_line, outcome_details, success_text
 from .results import failed
 
 _MESSAGE_TEMPLATES = {
@@ -76,7 +76,8 @@ _AMS_READ_DOMAINS = {
 }
 
 
-def _http_category(operation: str, status: object) -> str:
+def http_category(operation: str, status: object) -> str:
+    """The bounded category for one HTTP status (writes reuse the same mapping)."""
     shared_categories = {
         401: "authentication",
         403: "authorization",
@@ -115,7 +116,7 @@ def _classification(operation: str, error: BaseException) -> tuple[str, int]:
     if isinstance(error, DomainReadRefused):
         return error.category, 1
     if isinstance(error, (HealthCloudHTTPError, SDKError)):
-        return _http_category(operation, getattr(error, "status_code", None)), 1
+        return http_category(operation, getattr(error, "status_code", None)), 1
     if isinstance(error, (HealthCloudNetworkError, NetworkError)):
         return "transport", 1
     if isinstance(error, click.ClickException):
@@ -171,7 +172,7 @@ def _render_failure(envelope: dict, mode: str) -> None:
         # An unknown mutation outcome carries the read-only reconciliation the
         # operator must see before acting again; pretty is the default mode, so
         # dropping it here would only expose it under ``--output json``.
-        details = unknown_details(envelope)
+        details = outcome_details(envelope)
         if details:
             click.echo(details, err=True)
         return

{healthcloud_cli-3.7.8 → healthcloud_cli-3.7.9}/healthcloud_cli/ams/pretty.py

@@ -272,25 +272,38 @@ def _detail_lines(mapping: dict, depth: int = 0) -> list[str]:
     return lines
 
 
-def unknown_details(envelope: dict) -> str:
-    """Render the data and verification an ``unknown`` mutation envelope carries.
-
-    An unknown mutation outcome may already have committed, so the default
-    (pretty) mode must show the read-only reconciliation and
-    ``mutation_replayed: false`` the operator needs before acting again, not
-    just the bounded error line. Any other envelope renders as that one line.
+# Outcomes that carry a written-mutation evidence block. ``unknown`` means the
+# write may have committed and ``failed`` means it was provably sent but the
+# readback (or the server's refusal) says it did not land: both must show the
+# operator what was sent and what the saved state is. A plain read failure has
+# no such block and stays one line.
+_EVIDENCED_OUTCOMES = ("unknown", "failed")
+
+
+def outcome_details(envelope: dict) -> str:
+    """Render the data and verification a sent-mutation envelope carries.
+
+    An unknown mutation outcome may already have committed, and a failed one was
+    provably sent, so the default (pretty) mode must show the read-only
+    reconciliation, ``mutation_replayed: false`` and the ``saved_state`` the
+    operator needs before acting again, not just the bounded error line.
+
+    The block is gated on the envelope carrying ``data`` evidence, not on the
+    outcome alone: a local refusal built by ``failed(..., read_only=False)``
+    (every ``run_domain(read_only=False)`` refusal: teams, policies,
+    departments, guardrails, agents) was never sent, has no evidence to show,
+    and stays one line even though it carries a ``not_applicable`` verification.
     """
 
-    if envelope.get("outcome") != "unknown":
+    if envelope.get("outcome") not in _EVIDENCED_OUTCOMES:
         return ""
-    lines: list[str] = []
     data = envelope.get("data")
-    if isinstance(data, dict) and data:
-        lines.extend(_detail_lines(data))
+    if not isinstance(data, dict) or not data:
+        return ""
+    lines = _detail_lines(data)
     verification = envelope.get("verification")
     if isinstance(verification, dict) and verification:
-        if lines:
-            lines.append("")
+        lines.append("")
         lines.append("verification:")
         lines.extend(_detail_lines(verification, 1))
     return "\n".join(lines)

{healthcloud_cli-3.7.8 → healthcloud_cli-3.7.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "healthcloud-cli"
-version = "3.7.8"
+version = "3.7.9"
 description = "Command-line interface for the HealthCloud MCP gateway, generated from the shared MCP tool manifest."
 readme = "README.md"
 requires-python = ">=3.14"