healthcloud-cli 3.6.0__tar.gz → 3.7.1__tar.gz

{healthcloud_cli-3.6.0 → healthcloud_cli-3.7.1}/.gitignore

@@ -260,3 +260,5 @@ integration-tests/shared/test-assets/
 .ralph/
 /PROMPT.md
 .blind-peer-review/
+# Terraform CI runner-local diagnostics, inputs and sensitive plan bundles.
+/.kb-ci/

{healthcloud_cli-3.6.0 → healthcloud_cli-3.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.6.0
+Version: 3.7.1
 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
@@ -751,10 +751,14 @@ uv run --frozen hc ams departments delete --environment dev --tenant-id TENANT_I
   reports a `validation` refusal that names the department, the tenant that
   received it, and tells you to run `hc ams departments get` — it never claims
   a landed write was a stopped no-op.
-- If the transport times out or the connection drops mid-write, the write's
-  outcome is unknown: the CLI reports one `transport` error whose message says
-  the outcome is unknown and to check `hc ams departments get` before
-  retrying. It never re-sends the write on its own.
+- If the transport times out, the connection drops mid-write, or the server
+  answers an HTTP 5xx/408 before a readable result, the write's outcome is
+  unknown: the CLI exits 1 with an `unknown` envelope
+  (`verification.saved_state: unknown`, `verification.side_effects:
+  unverified`, `data.mutation_replayed: false`, and
+  `data.reconciliation.status: not_read`) whose message says the outcome is
+  unknown and to check `hc ams departments get` before retrying. It never
+  re-sends the write and never re-reads on its own.
 
 Read-only team listing and inspection are also complete and unpaged. The bounded
 projection omits descriptions and creator identities; it includes evaluation-suite
@@ -797,10 +801,14 @@ uv run --frozen hc ams teams delete --environment dev --tenant-id TENANT_ID   --
   `validation` refusal that reports the landed write truthfully: it names the
   team and the tenant that actually received it and points to `hc ams teams
   get` — it never claims a landed write was stopped.
-- If the transport times out or the connection drops mid-write, the write's
-  outcome is unknown: the CLI reports one `transport` error whose message says
-  the outcome is unknown and to check `hc ams teams get` before retrying. It
-  never re-sends the write on its own.
+- If the transport times out, the connection drops mid-write, or the server
+  answers an HTTP 5xx/408 before a readable result, the write's outcome is
+  unknown: the CLI exits 1 with an `unknown` envelope
+  (`verification.saved_state: unknown`, `verification.side_effects:
+  unverified`, `data.mutation_replayed: false`, and
+  `data.reconciliation.status: not_read`) whose message says the outcome is
+  unknown and to check `hc ams teams get` before retrying. It never re-sends
+  the write and never re-reads on its own.
 
 The organization hierarchy is the backend-built department/team/agent tree. The
 CLI preserves its order and nesting without issuing entity reads, joining records,
@@ -862,10 +870,14 @@ uv run --frozen hc ams skills delete --environment dev --tenant-id TENANT_ID --s
   landed write truthfully: it names the skill and the tenant that actually
   received it and points to `hc ams skills get` — it never claims a landed
   write was stopped.
-- If the transport times out or the connection drops mid-write, the write's
-  outcome is unknown: the CLI reports one `transport` error whose message says
-  the outcome is unknown and to check `hc ams skills get` before retrying. It
-  never re-sends the write on its own.
+- If the transport times out, the connection drops mid-write, or the server
+  answers an HTTP 5xx/408 before a readable result, the write's outcome is
+  unknown: the CLI exits 1 with an `unknown` envelope
+  (`verification.saved_state: unknown`, `verification.side_effects:
+  unverified`, `data.mutation_replayed: false`, and
+  `data.reconciliation.status: not_read`) whose message says the outcome is
+  unknown and to check `hc ams skills get` before retrying. It never re-sends
+  the write and never re-reads on its own.
 
 Read-only policy catalog listing and inspection are complete and unpaged. The
 bounded projection includes only policy IDs, names, department IDs, guardrail
@@ -897,8 +909,8 @@ Policies have an `active` lifecycle flag, so `activate` and `deactivate`
 commands exist (they PUT the `active` field):
 
 ```bash
-uv run --frozen hc ams policies create --environment dev --tenant-id TENANT_ID --name "Appointment Safety" --department-id DEPARTMENT_ID --created-by-user-id ADMIN_USER_ID [--description TEXT] [--content TEXT] [--guardrail-ids GUARDRAIL_ID ...]
-uv run --frozen hc ams policies update --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID [--name NAME] [--description TEXT] [--content TEXT] [--guardrail-ids GUARDRAIL_ID ... | --clear-guardrail-ids]
+uv run --frozen hc ams policies create --environment dev --tenant-id TENANT_ID --name "Appointment Safety" --department-id DEPARTMENT_ID --created-by-user-id ADMIN_USER_ID [--description TEXT] [--content TEXT | --content-file PATH] [--guardrail-ids GUARDRAIL_ID ...]
+uv run --frozen hc ams policies update --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID [--name NAME] [--description TEXT] [--content TEXT | --content-file PATH] [--guardrail-ids GUARDRAIL_ID ... | --clear-guardrail-ids]
 uv run --frozen hc ams policies activate --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
 uv run --frozen hc ams policies deactivate --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
 uv run --frozen hc ams policies delete --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
@@ -911,6 +923,29 @@ uv run --frozen hc ams policies delete --environment dev --tenant-id TENANT_ID -
   server does not validate that `--guardrail-ids` reference real guardrails
   (blank guardrail IDs are rejected client-side). `--content` is write-only:
   it is sent but never echoed back.
+- The protected policy content can also arrive from an owner-only file, which
+  keeps it out of the command line entirely (argv, the process table under
+  `ps`/`/proc/*/cmdline`, shell history and CI logs all see only the path):
+
+  ```bash
+  uv run --frozen hc ams policies create --environment dev --tenant-id TENANT_ID --name "Appointment Safety" --department-id DEPARTMENT_ID --created-by-user-id ADMIN_USER_ID --content-file PATH
+  uv run --frozen hc ams policies update --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID --content-file PATH
+  ```
+
+  The file is read locally, before the login check and any request, by the same
+  reader the sessions commands use: it must be a readable owner-only regular
+  text file (no symlinks, no directories, not group- or world-readable) and
+  must hold 1-20000 characters. Its content is never printed, and an invalid,
+  empty or oversized file is refused locally with a message that names the
+  discipline, never the text. The output is identical to the inline form:
+  `policies.create` / `policies.update` with `data.policy`.
+- Exactly one content source is accepted per write: passing `--content` with
+  `--content-file` is a usage error (exit 2) that sends nothing. The inline
+  `--content` flag remains supported for convenience and remains exposed in
+  argv, the process table and shell history — use the file channel for
+  anything sensitive. An empty `--content ""` on `update` is still the
+  documented clear; an empty `--content-file` is a `validation` refusal, so a
+  truncated or misdirected file can never clear protected content by accident.
 - `update` sends only the options you pass (an empty `--description ""` or
   `--content ""` clears it; `--clear-guardrail-ids` sends an explicit empty
   list to clear the policy's guardrail bindings); it refuses with exit 1
@@ -931,10 +966,14 @@ uv run --frozen hc ams policies delete --environment dev --tenant-id TENANT_ID -
   landed write truthfully: it names the policy and the tenant that actually
   received it and points to `hc ams policies get` — it never claims a landed
   write was stopped.
-- If the transport times out or the connection drops mid-write, the write's
-  outcome is unknown: the CLI reports one `transport` error whose message says
-  the outcome is unknown and to check `hc ams policies get` before retrying.
-  It never re-sends the write on its own.
+- If the transport times out, the connection drops mid-write, or the server
+  answers an HTTP 5xx/408 before a readable result, the write's outcome is
+  unknown: the CLI exits 1 with an `unknown` envelope
+  (`verification.saved_state: unknown`, `verification.side_effects:
+  unverified`, `data.mutation_replayed: false`, and
+  `data.reconciliation.status: not_read`) whose message says the outcome is
+  unknown and to check `hc ams policies get` before retrying. It never
+  re-sends the write and never re-reads on its own.
 
 Governed authoring sessions and their messages are first-class commands over the
 VibeCoder session routes. Creating a session and appending a message make no model
@@ -947,9 +986,9 @@ is refused locally:
 ```bash
 uv run --frozen hc ams sessions list --environment dev --tenant-id TENANT_ID [--limit N]
 uv run --frozen hc ams sessions get --environment dev --tenant-id TENANT_ID --session-id SESSION_ID
-uv run --frozen hc ams sessions create --environment dev --tenant-id TENANT_ID [--agent-id AGENT_ID] [--mode plan|implement] [--initial-prompt TEXT]
+uv run --frozen hc ams sessions create --environment dev --tenant-id TENANT_ID [--agent-id AGENT_ID] [--mode plan|implement] [--initial-prompt TEXT | --initial-prompt-file PATH]
 uv run --frozen hc ams sessions messages list --environment dev --tenant-id TENANT_ID --session-id SESSION_ID [--limit N]
-uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENANT_ID --session-id SESSION_ID --content TEXT [--mode plan|implement] [--idempotency-key KEY]
+uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENANT_ID --session-id SESSION_ID [--content TEXT | --content-file PATH] [--mode plan|implement] [--idempotency-key KEY]
 ```
 
 - `list` emits `operation: "sessions.list"`, `data.sessions` (bounded projections
@@ -966,6 +1005,30 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
   mode, plan ID, model, timestamps) plus `data.idempotency_key` when a key was
   supplied. Protected free text — `--initial-prompt` and `--content` — is sent to
   the server but never appears in the envelope, a refusal, a diagnostic or a log.
+- The protected free text can also arrive from an owner-only file, which keeps it
+  out of the command line entirely (argv, the process table under
+  `ps`/`/proc/*/cmdline`, shell history and CI logs all see only the path):
+
+  ```bash
+  uv run --frozen hc ams sessions create --environment dev --tenant-id TENANT_ID --initial-prompt-file PATH
+  uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENANT_ID --session-id SESSION_ID --content-file PATH
+  ```
+
+  The file is read locally, before the login check and any request, by the same
+  reader `hc ams sessions plans generate --prompt-file` uses: it must be a
+  readable owner-only regular text file (no symlinks, no directories, not
+  group- or world-readable), and must hold 1-20000 characters — the same bound
+  the inline flag is now held to, so neither channel can carry an empty or
+  over-long value past the local check. Its content is never printed, and an
+  invalid, empty or oversized file is refused locally with a message that
+  names the discipline, never the text. The output is identical to the inline form: `sessions.create`
+  with `data.session`, `sessions.messages.add` with `data.message`.
+- Exactly one source is accepted per field. Passing `--initial-prompt` with
+  `--initial-prompt-file`, or `--content` with `--content-file`, is a usage
+  error (exit 2) that sends nothing; `messages add` with neither is the same
+  usage error. The inline `--initial-prompt` and `--content` flags remain
+  supported for convenience, and remain exposed in argv, the process table and
+  shell history — use the file channel for anything sensitive.
 - `--initial-prompt` becomes the session's first `user` message in the same
   server transaction; `hc ams sessions messages list` shows it afterwards.
 - `--mode implement` is not available from the server yet: `create` reports one

{healthcloud_cli-3.6.0 → healthcloud_cli-3.7.1}/README.md

@@ -733,10 +733,14 @@ uv run --frozen hc ams departments delete --environment dev --tenant-id TENANT_I
   reports a `validation` refusal that names the department, the tenant that
   received it, and tells you to run `hc ams departments get` — it never claims
   a landed write was a stopped no-op.
-- If the transport times out or the connection drops mid-write, the write's
-  outcome is unknown: the CLI reports one `transport` error whose message says
-  the outcome is unknown and to check `hc ams departments get` before
-  retrying. It never re-sends the write on its own.
+- If the transport times out, the connection drops mid-write, or the server
+  answers an HTTP 5xx/408 before a readable result, the write's outcome is
+  unknown: the CLI exits 1 with an `unknown` envelope
+  (`verification.saved_state: unknown`, `verification.side_effects:
+  unverified`, `data.mutation_replayed: false`, and
+  `data.reconciliation.status: not_read`) whose message says the outcome is
+  unknown and to check `hc ams departments get` before retrying. It never
+  re-sends the write and never re-reads on its own.
 
 Read-only team listing and inspection are also complete and unpaged. The bounded
 projection omits descriptions and creator identities; it includes evaluation-suite
@@ -779,10 +783,14 @@ uv run --frozen hc ams teams delete --environment dev --tenant-id TENANT_ID   --
   `validation` refusal that reports the landed write truthfully: it names the
   team and the tenant that actually received it and points to `hc ams teams
   get` — it never claims a landed write was stopped.
-- If the transport times out or the connection drops mid-write, the write's
-  outcome is unknown: the CLI reports one `transport` error whose message says
-  the outcome is unknown and to check `hc ams teams get` before retrying. It
-  never re-sends the write on its own.
+- If the transport times out, the connection drops mid-write, or the server
+  answers an HTTP 5xx/408 before a readable result, the write's outcome is
+  unknown: the CLI exits 1 with an `unknown` envelope
+  (`verification.saved_state: unknown`, `verification.side_effects:
+  unverified`, `data.mutation_replayed: false`, and
+  `data.reconciliation.status: not_read`) whose message says the outcome is
+  unknown and to check `hc ams teams get` before retrying. It never re-sends
+  the write and never re-reads on its own.
 
 The organization hierarchy is the backend-built department/team/agent tree. The
 CLI preserves its order and nesting without issuing entity reads, joining records,
@@ -844,10 +852,14 @@ uv run --frozen hc ams skills delete --environment dev --tenant-id TENANT_ID --s
   landed write truthfully: it names the skill and the tenant that actually
   received it and points to `hc ams skills get` — it never claims a landed
   write was stopped.
-- If the transport times out or the connection drops mid-write, the write's
-  outcome is unknown: the CLI reports one `transport` error whose message says
-  the outcome is unknown and to check `hc ams skills get` before retrying. It
-  never re-sends the write on its own.
+- If the transport times out, the connection drops mid-write, or the server
+  answers an HTTP 5xx/408 before a readable result, the write's outcome is
+  unknown: the CLI exits 1 with an `unknown` envelope
+  (`verification.saved_state: unknown`, `verification.side_effects:
+  unverified`, `data.mutation_replayed: false`, and
+  `data.reconciliation.status: not_read`) whose message says the outcome is
+  unknown and to check `hc ams skills get` before retrying. It never re-sends
+  the write and never re-reads on its own.
 
 Read-only policy catalog listing and inspection are complete and unpaged. The
 bounded projection includes only policy IDs, names, department IDs, guardrail
@@ -879,8 +891,8 @@ Policies have an `active` lifecycle flag, so `activate` and `deactivate`
 commands exist (they PUT the `active` field):
 
 ```bash
-uv run --frozen hc ams policies create --environment dev --tenant-id TENANT_ID --name "Appointment Safety" --department-id DEPARTMENT_ID --created-by-user-id ADMIN_USER_ID [--description TEXT] [--content TEXT] [--guardrail-ids GUARDRAIL_ID ...]
-uv run --frozen hc ams policies update --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID [--name NAME] [--description TEXT] [--content TEXT] [--guardrail-ids GUARDRAIL_ID ... | --clear-guardrail-ids]
+uv run --frozen hc ams policies create --environment dev --tenant-id TENANT_ID --name "Appointment Safety" --department-id DEPARTMENT_ID --created-by-user-id ADMIN_USER_ID [--description TEXT] [--content TEXT | --content-file PATH] [--guardrail-ids GUARDRAIL_ID ...]
+uv run --frozen hc ams policies update --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID [--name NAME] [--description TEXT] [--content TEXT | --content-file PATH] [--guardrail-ids GUARDRAIL_ID ... | --clear-guardrail-ids]
 uv run --frozen hc ams policies activate --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
 uv run --frozen hc ams policies deactivate --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
 uv run --frozen hc ams policies delete --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
@@ -893,6 +905,29 @@ uv run --frozen hc ams policies delete --environment dev --tenant-id TENANT_ID -
   server does not validate that `--guardrail-ids` reference real guardrails
   (blank guardrail IDs are rejected client-side). `--content` is write-only:
   it is sent but never echoed back.
+- The protected policy content can also arrive from an owner-only file, which
+  keeps it out of the command line entirely (argv, the process table under
+  `ps`/`/proc/*/cmdline`, shell history and CI logs all see only the path):
+
+  ```bash
+  uv run --frozen hc ams policies create --environment dev --tenant-id TENANT_ID --name "Appointment Safety" --department-id DEPARTMENT_ID --created-by-user-id ADMIN_USER_ID --content-file PATH
+  uv run --frozen hc ams policies update --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID --content-file PATH
+  ```
+
+  The file is read locally, before the login check and any request, by the same
+  reader the sessions commands use: it must be a readable owner-only regular
+  text file (no symlinks, no directories, not group- or world-readable) and
+  must hold 1-20000 characters. Its content is never printed, and an invalid,
+  empty or oversized file is refused locally with a message that names the
+  discipline, never the text. The output is identical to the inline form:
+  `policies.create` / `policies.update` with `data.policy`.
+- Exactly one content source is accepted per write: passing `--content` with
+  `--content-file` is a usage error (exit 2) that sends nothing. The inline
+  `--content` flag remains supported for convenience and remains exposed in
+  argv, the process table and shell history — use the file channel for
+  anything sensitive. An empty `--content ""` on `update` is still the
+  documented clear; an empty `--content-file` is a `validation` refusal, so a
+  truncated or misdirected file can never clear protected content by accident.
 - `update` sends only the options you pass (an empty `--description ""` or
   `--content ""` clears it; `--clear-guardrail-ids` sends an explicit empty
   list to clear the policy's guardrail bindings); it refuses with exit 1
@@ -913,10 +948,14 @@ uv run --frozen hc ams policies delete --environment dev --tenant-id TENANT_ID -
   landed write truthfully: it names the policy and the tenant that actually
   received it and points to `hc ams policies get` — it never claims a landed
   write was stopped.
-- If the transport times out or the connection drops mid-write, the write's
-  outcome is unknown: the CLI reports one `transport` error whose message says
-  the outcome is unknown and to check `hc ams policies get` before retrying.
-  It never re-sends the write on its own.
+- If the transport times out, the connection drops mid-write, or the server
+  answers an HTTP 5xx/408 before a readable result, the write's outcome is
+  unknown: the CLI exits 1 with an `unknown` envelope
+  (`verification.saved_state: unknown`, `verification.side_effects:
+  unverified`, `data.mutation_replayed: false`, and
+  `data.reconciliation.status: not_read`) whose message says the outcome is
+  unknown and to check `hc ams policies get` before retrying. It never
+  re-sends the write and never re-reads on its own.
 
 Governed authoring sessions and their messages are first-class commands over the
 VibeCoder session routes. Creating a session and appending a message make no model
@@ -929,9 +968,9 @@ is refused locally:
 ```bash
 uv run --frozen hc ams sessions list --environment dev --tenant-id TENANT_ID [--limit N]
 uv run --frozen hc ams sessions get --environment dev --tenant-id TENANT_ID --session-id SESSION_ID
-uv run --frozen hc ams sessions create --environment dev --tenant-id TENANT_ID [--agent-id AGENT_ID] [--mode plan|implement] [--initial-prompt TEXT]
+uv run --frozen hc ams sessions create --environment dev --tenant-id TENANT_ID [--agent-id AGENT_ID] [--mode plan|implement] [--initial-prompt TEXT | --initial-prompt-file PATH]
 uv run --frozen hc ams sessions messages list --environment dev --tenant-id TENANT_ID --session-id SESSION_ID [--limit N]
-uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENANT_ID --session-id SESSION_ID --content TEXT [--mode plan|implement] [--idempotency-key KEY]
+uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENANT_ID --session-id SESSION_ID [--content TEXT | --content-file PATH] [--mode plan|implement] [--idempotency-key KEY]
 ```
 
 - `list` emits `operation: "sessions.list"`, `data.sessions` (bounded projections
@@ -948,6 +987,30 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
   mode, plan ID, model, timestamps) plus `data.idempotency_key` when a key was
   supplied. Protected free text — `--initial-prompt` and `--content` — is sent to
   the server but never appears in the envelope, a refusal, a diagnostic or a log.
+- The protected free text can also arrive from an owner-only file, which keeps it
+  out of the command line entirely (argv, the process table under
+  `ps`/`/proc/*/cmdline`, shell history and CI logs all see only the path):
+
+  ```bash
+  uv run --frozen hc ams sessions create --environment dev --tenant-id TENANT_ID --initial-prompt-file PATH
+  uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENANT_ID --session-id SESSION_ID --content-file PATH
+  ```
+
+  The file is read locally, before the login check and any request, by the same
+  reader `hc ams sessions plans generate --prompt-file` uses: it must be a
+  readable owner-only regular text file (no symlinks, no directories, not
+  group- or world-readable), and must hold 1-20000 characters — the same bound
+  the inline flag is now held to, so neither channel can carry an empty or
+  over-long value past the local check. Its content is never printed, and an
+  invalid, empty or oversized file is refused locally with a message that
+  names the discipline, never the text. The output is identical to the inline form: `sessions.create`
+  with `data.session`, `sessions.messages.add` with `data.message`.
+- Exactly one source is accepted per field. Passing `--initial-prompt` with
+  `--initial-prompt-file`, or `--content` with `--content-file`, is a usage
+  error (exit 2) that sends nothing; `messages add` with neither is the same
+  usage error. The inline `--initial-prompt` and `--content` flags remain
+  supported for convenience, and remain exposed in argv, the process table and
+  shell history — use the file channel for anything sensitive.
 - `--initial-prompt` becomes the session's first `user` message in the same
   server transaction; `hc ams sessions messages list` shows it afterwards.
 - `--mode implement` is not available from the server yet: `create` reports one

{healthcloud_cli-3.6.0 → healthcloud_cli-3.7.1}/healthcloud_cli/ams/departments/operations.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from ..context import AmsDependencies
 from ..domain_errors import DomainReadRefused
-from ..results import succeeded
+from ..results import is_unknown_write_status, succeeded, unknown_write
 from ..target import TenantTarget
 from .projections import department_projection
 
@@ -27,6 +27,18 @@ UNKNOWN_OUTCOME = (
     "department's current server state before deciding whether to retry."
 )
 
+UNKNOWN_HTTP_OUTCOME = (
+    "The department write was sent once and its outcome is now unknown: the server answered with an "
+    "error status before a readable result, so the request may have been processed. Run "
+    "`hc ams departments get` to check the department's current server state before deciding whether "
+    "to retry."
+)
+
+UNKNOWN_RECONCILIATION = (
+    "This command did not re-read the department after the uncertain write; run "
+    "`hc ams departments list` before doing anything else."
+)
+
 
 def _department_id(value: str) -> str:
     if not isinstance(value, str) or not value.strip():
@@ -140,11 +152,26 @@ def create_department(
             )
         except HealthCloudNetworkError:
             # Sent once: the request may have landed; the outcome is unknown, never retried here.
-            raise DepartmentWriteRefused("transport", UNKNOWN_OUTCOME) from None
+            unknown_write(
+                "departments.create",
+                _target(target),
+                UNKNOWN_OUTCOME,
+                {"department": None},
+                reconciliation_detail=UNKNOWN_RECONCILIATION,
+            )
         except HealthCloudHTTPError as error:
             refusal = _create_not_found(error, parent_department_id)
             if refusal is not None:
                 raise refusal from error
+            if is_unknown_write_status(getattr(error, "status_code", None)):
+                # A 5xx/408 may have committed server-side: report it as unknown, never a retry shape.
+                unknown_write(
+                    "departments.create",
+                    _target(target),
+                    UNKNOWN_HTTP_OUTCOME,
+                    {"department": None},
+                    reconciliation_detail=UNKNOWN_RECONCILIATION,
+                )
             raise
     # The write has already landed server-side; a mismatching readback must never be
     # reported as a stopped no-op. Name the tenant that actually received it.
@@ -174,11 +201,25 @@ def update_department(
         try:
             department = resource.update(department_id, **fields)
         except HealthCloudNetworkError:
-            raise DepartmentWriteRefused("transport", UNKNOWN_OUTCOME) from None
+            unknown_write(
+                "departments.update",
+                _target(target, department_id),
+                UNKNOWN_OUTCOME,
+                {"department": None},
+                reconciliation_detail=UNKNOWN_RECONCILIATION,
+            )
         except HealthCloudHTTPError as error:
             refusal = _not_found(error, department_id)
             if refusal is not None:
                 raise refusal from error
+            if is_unknown_write_status(getattr(error, "status_code", None)):
+                unknown_write(
+                    "departments.update",
+                    _target(target, department_id),
+                    UNKNOWN_HTTP_OUTCOME,
+                    {"department": None},
+                    reconciliation_detail=UNKNOWN_RECONCILIATION,
+                )
             raise
     _identity(department, target, department_id)
     return _write_result("departments.update", target, department_id, {"department": department_projection(department)})
@@ -193,11 +234,25 @@ def _lifecycle(dependencies: AmsDependencies, target: TenantTarget, department_i
         try:
             department = getattr(resource, method)(department_id)
         except HealthCloudNetworkError:
-            raise DepartmentWriteRefused("transport", UNKNOWN_OUTCOME) from None
+            unknown_write(
+                f"departments.{method}",
+                _target(target, department_id),
+                UNKNOWN_OUTCOME,
+                {"department": None},
+                reconciliation_detail=UNKNOWN_RECONCILIATION,
+            )
         except HealthCloudHTTPError as error:
             refusal = _not_found(error, department_id)
             if refusal is not None:
                 raise refusal from error
+            if is_unknown_write_status(getattr(error, "status_code", None)):
+                unknown_write(
+                    f"departments.{method}",
+                    _target(target, department_id),
+                    UNKNOWN_HTTP_OUTCOME,
+                    {"department": None},
+                    reconciliation_detail=UNKNOWN_RECONCILIATION,
+                )
             raise
     _identity(department, target, department_id)
     return _write_result(
@@ -225,10 +280,24 @@ def delete_department(dependencies: AmsDependencies, target: TenantTarget, depar
         try:
             resource.delete(department_id)
         except HealthCloudNetworkError:
-            raise DepartmentWriteRefused("transport", UNKNOWN_OUTCOME) from None
+            unknown_write(
+                "departments.delete",
+                _target(target, department_id),
+                UNKNOWN_OUTCOME,
+                {"deleted": None},
+                reconciliation_detail=UNKNOWN_RECONCILIATION,
+            )
         except HealthCloudHTTPError as error:
             refusal = _not_found(error, department_id)
             if refusal is not None:
                 raise refusal from error
+            if is_unknown_write_status(getattr(error, "status_code", None)):
+                unknown_write(
+                    "departments.delete",
+                    _target(target, department_id),
+                    UNKNOWN_HTTP_OUTCOME,
+                    {"deleted": None},
+                    reconciliation_detail=UNKNOWN_RECONCILIATION,
+                )
             raise
     return _write_result("departments.delete", target, department_id, {"deleted": True})

{healthcloud_cli-3.6.0 → healthcloud_cli-3.7.1}/healthcloud_cli/ams/output.py

@@ -6,11 +6,16 @@ import hashlib
 import json
 import os
 import stat
+from collections.abc import Callable
 from contextlib import contextmanager
 from pathlib import Path
 
 import click
 
+# One bound for every protected free-text field the CLI accepts, whichever
+# channel it arrives on (#834): the same value the server enforces.
+PROTECTED_TEXT_MAX_CHARS = 20000
+
 
 def canonical(value: object) -> str:
     return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
@@ -91,6 +96,57 @@ def read_private_text(path: Path, *, maximum: int) -> str:
         ) from None
 
 
+def protected_text(
+    inline: str | None,
+    path: str | None,
+    *,
+    flag: str,
+    file_flag: str,
+    refuse: Callable[[str, str], BaseException],
+    required: bool = False,
+    allow_empty_inline: bool = False,
+) -> str | None:
+    """Resolve one protected free-text field from exactly one input channel.
+
+    ``--<field>`` keeps working for convenience but lands in argv, the process
+    table and shell history; ``--<field>-file`` reads the same text from one
+    owner-only file instead. Exactly one source is allowed, and both channels
+    are bounded identically, so neither can carry an over-long value past the
+    local check the other applies.
+
+    ``required`` makes "no source at all" a refusal here, in the Click-free
+    layer, so the invariant does not depend on the adapter. Empty text is
+    refused on both channels unless the caller documents an empty inline value
+    as a clear (``hc ams policies update --content ""``); an empty file is
+    always refused, so a truncated or misdirected file can never clear a
+    protected field by accident. ``refuse`` builds the caller's own categorized
+    refusal, and no refusal quotes the text itself.
+    """
+
+    if inline is not None and path is not None:
+        raise refuse("validation", f"Pass {flag} or {file_flag}, not both; nothing was sent.")
+    if inline is None and path is None:
+        if not required:
+            return None
+        raise refuse("validation", f"Pass {flag} or {file_flag}; nothing was sent.")
+    if path is not None:
+        if not isinstance(path, str) or not path.strip():
+            raise refuse("validation", f"Explicit {file_flag} file path required.")
+        text = read_private_text(Path(path), maximum=PROTECTED_TEXT_MAX_CHARS)
+        if not text:
+            raise refuse("validation", f"The file given to {file_flag} is empty; nothing was sent.")
+        return text
+    if len(inline) > PROTECTED_TEXT_MAX_CHARS:
+        raise refuse(
+            "validation",
+            f"{flag} is longer than {PROTECTED_TEXT_MAX_CHARS} characters; nothing was sent. "
+            f"Pass a shorter value, or the same text with {file_flag}.",
+        )
+    if not inline and not allow_empty_inline:
+        raise refuse("validation", f"{flag} is empty; nothing was sent. Pass the text, or {file_flag} holding it.")
+    return inline
+
+
 @contextmanager
 def _private_stream(path: Path, newline: str | None = None):
     """Reserve output before network calls, never overwrite, clean failed work."""

{healthcloud_cli-3.6.0 → healthcloud_cli-3.7.1}/healthcloud_cli/ams/policies/commands.py

@@ -88,7 +88,15 @@ def create_create_command(dependencies: AmsDependencies) -> click.Command:
     @click.option(
         "--content",
         default=None,
-        help="Policy content (write-only; never echoed in command output).",
+        help="Policy content (write-only; never echoed in command output). Exposed in argv, the process "
+        "table and shell history: prefer --content-file.",
+    )
+    @click.option(
+        "--content-file",
+        default=None,
+        type=click.Path(dir_okay=False),
+        help="Owner-only text file holding the policy content, so the text never enters argv or shell "
+        "history (1-20000 characters). Cannot be combined with --content.",
     )
     @click.option(
         "--guardrail-ids",
@@ -106,7 +114,10 @@ def create_create_command(dependencies: AmsDependencies) -> click.Command:
         description: str | None,
         content: str | None,
         guardrail_ids: tuple[str, ...],
+        content_file: str | None,
     ) -> None:
+        if content is not None and content_file is not None:
+            raise click.UsageError("Pass --content or --content-file, not both; nothing was sent.")
         target_data = {"environment": environment, "tenant_id": tenant_id, "name": name}
 
         def execute():
@@ -123,6 +134,7 @@ def create_create_command(dependencies: AmsDependencies) -> click.Command:
                 description=description,
                 content=content,
                 guardrail_ids=list(guardrail_ids) or None,
+                content_file=content_file,
             )
 
         run_domain("policies.create", target_data, execute, read_only=False)
@@ -140,7 +152,16 @@ def create_update_command(dependencies: AmsDependencies) -> click.Command:
     @click.option(
         "--content",
         default=None,
-        help="New policy content; an empty value clears it (write-only; never echoed).",
+        help="New policy content; an empty value clears it (write-only; never echoed). Exposed in argv, "
+        "the process table and shell history: prefer --content-file.",
+    )
+    @click.option(
+        "--content-file",
+        default=None,
+        type=click.Path(dir_okay=False),
+        help="Owner-only text file holding the new policy content, so the text never enters argv or "
+        "shell history (1-20000 characters). An empty file is refused. Cannot be combined with "
+        "--content.",
     )
     @click.option(
         "--guardrail-ids",
@@ -163,7 +184,10 @@ def create_update_command(dependencies: AmsDependencies) -> click.Command:
         content: str | None,
         guardrail_ids: tuple[str, ...],
         clear_guardrail_ids: bool,
+        content_file: str | None,
     ) -> None:
+        if content is not None and content_file is not None:
+            raise click.UsageError("Pass --content or --content-file, not both; nothing was sent.")
         target_data = {
             "environment": environment,
             "tenant_id": tenant_id,
@@ -181,14 +205,14 @@ def create_update_command(dependencies: AmsDependencies) -> click.Command:
             if description is not None:
                 fields["description"] = description or None
             if content is not None:
-                fields["content"] = content or None
+                fields["content"] = content
             if guardrail_ids:
                 fields["guardrail_ids"] = list(guardrail_ids)
             elif clear_guardrail_ids:
                 fields["guardrail_ids"] = []
-            if not fields:
+            if not fields and content_file is None:
                 raise click.UsageError("Nothing to update; pass at least one field option.")
-            return update_policy(dependencies, target, policy_id, fields=fields)
+            return update_policy(dependencies, target, policy_id, fields=fields, content_file=content_file)
 
         run_domain("policies.update", target_data, execute, read_only=False)