feat(fire): add --exit-criteria + --idempotency-key flags (cueapi #632 + #683 parity)

Extends the existing fire command with two flags covering recently-shipped
server features. --send-at was already there from a prior port (#618).

  --exit-criteria (repeatable, max 20)
      §14 work-verification-light required-assertion keys (cueapi #632).
      Receiver MUST report values for every key under outcome.assertions;
      missing keys mark the execution verification_failed. Pass empty
      string '' once to opt out of cue-level required_assertions for this
      fire (server distinguishes [] = explicit opt-out from None = use
      cue-level).

  --idempotency-key (≤256 chars)
      Opaque dedup key (cueapi #683 Phase 2). Same key + same body within
      24h returns the cached execution; same key + different body returns
      409 idempotency_key_conflict.

Implementation pin (caught earlier on cueapi-python #33 + cueapi-mcp #29):
idempotency_key is a BODY field on cues fire, NOT the Idempotency-Key
header. Server's FireRequest schema diverges from the messaging primitive's
header-based idempotency. Help text + load-bearing test pin this so a
future refactor doesn't 'simplify' to header-based (which would silently
not work — server FireRequest is extra='forbid' for unknown body fields,
ignores headers in body parsing).

Tests added (3):
  - test_fire_help: pins all 5 flags appear in --help (--payload-override,
    --merge-strategy, --send-at, --exit-criteria, --idempotency-key)
  - test_fire_exit_criteria_repeatable_via_help: validates click parser
    accepts repeated --exit-criteria flags
  - test_fire_help_pins_idempotency_key_as_body_field: load-bearing pin
    against future header-refactor

185/185 tests pass (was 183; 2 new + parser-validation added inline).

Source: drift audit handoff/cueapi-package-drift-2026-05-06; Backlog
rows "Parity port: PR #632 → cueapi-cli" + "PR #683 not in backlog
(folded in same-day)". Triggered by cueapi-main confirming bandwidth
on cueapi-cli lane this session ([CC-CUEAPI-DOC-DEBT-CLOSED-DISCIPLINE-
CODIFIED]).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mikemolinet

cueapi/cli.py

@@ -464,13 +464,38 @@ def delete(ctx: click.Context, cue_id: str, yes: bool) -> None:
         "'fire now' (idempotent — no error). Hosted PR #618."
     ),
 )
+@click.option(
+    "--exit-criteria",
+    "exit_criteria",
+    multiple=True,
+    help=(
+        "Required-assertion key for §14 work-verification-light (hosted PR #632). "
+        "Repeat the flag for multiple keys (max 20). Receiver MUST report values for "
+        "every key under outcome.assertions; missing keys mark the execution "
+        "verification_failed. Pass --exit-criteria '' once to explicitly opt out of "
+        "cue-level required_assertions for this fire."
+    ),
+)
+@click.option(
+    "--idempotency-key",
+    "idempotency_key",
+    default=None,
+    help=(
+        "Opaque dedup key (≤256 chars, hosted PR #683). Same key on the same cue within "
+        "24h returns the cached execution without firing again. Same key + DIFFERENT body "
+        "returns 409 idempotency_key_conflict. Sent as a BODY field on cues fire (server "
+        "FireRequest schema; diverges from messaging primitive's Idempotency-Key header)."
+    ),
+)
 @click.pass_context
 def fire(
     ctx: click.Context,
     cue_id: str,
     payload_override: Optional[str],
     merge_strategy: Optional[str],
     send_at: Optional[str],
+    exit_criteria: tuple,
+    idempotency_key: Optional[str],
 ) -> None:
     """Fire an existing cue immediately, optionally overriding its payload."""
     body: dict = {}
@@ -483,6 +508,16 @@ def fire(
         body["merge_strategy"] = merge_strategy
     if send_at:
         body["send_at"] = send_at
+    if exit_criteria:
+        # click multiple=True yields a tuple. Single '' entry opts out by sending [].
+        if "" in exit_criteria:
+            body["exit_criteria"] = []
+        else:
+            body["exit_criteria"] = list(exit_criteria)
+    if idempotency_key:
+        # Body field on cues fire (NOT header — server FireRequest schema diverges
+        # from messaging primitive's Idempotency-Key header convention).
+        body["idempotency_key"] = idempotency_key
 
     try:
         with CueAPIClient(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile")) as client:

tests/test_cli.py

@@ -151,6 +151,36 @@ def test_fire_help():
     assert "fire" in result.output.lower()
     assert "--payload-override" in result.output
     assert "--merge-strategy" in result.output
+    # PR #618 + #632 + #683 parity
+    assert "--send-at" in result.output
+    assert "--exit-criteria" in result.output
+    assert "--idempotency-key" in result.output
+
+
+def test_fire_exit_criteria_repeatable_via_help():
+    """--exit-criteria takes multiple values (click multiple=True). Verify the
+    parser accepts repeated flags by passing them alongside --help."""
+    result = runner.invoke(
+        main,
+        [
+            "fire", "cue_x",
+            "--exit-criteria", "task_completed",
+            "--exit-criteria", "result_valid",
+            "--help",  # short-circuits actual fire — we just want parse to accept
+        ],
+    )
+    assert result.exit_code == 0
+
+
+def test_fire_help_pins_idempotency_key_as_body_field():
+    """Pin: the help text MUST call out that idempotency_key flows as a body
+    field on cues fire (NOT a header), to prevent a future 'simplifying'
+    refactor that moves it to a header — server's FireRequest schema is
+    extra='forbid' and would NOT see it as a header. Same divergence I caught
+    on cueapi-python #33 + cueapi-mcp #29."""
+    result = runner.invoke(main, ["fire", "--help"])
+    output = result.output.lower()
+    assert "body field" in output or "body" in output
 
 
 def test_fire_requires_cue_id():