deepsieve-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{deepsieve_cli-0.5.0 → deepsieve_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: deepsieve-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: DeepSieve CLI — run cited deep research from your terminal
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27
@@ -31,6 +31,7 @@ deepsieve whoami                              # identity, organization, active B
 deepsieve runs create --query "..." --dry-run # free simulated run (~15s)
 deepsieve runs create --blueprint <id> --query "..." --wait  # real run: spends credits
 deepsieve runs create --blueprint <id> --seeds "..." --allowed-source "*.gov"  # only cite these
+deepsieve runs create --blueprint <id> --query "..." --expected-total 1000  # refuse (charge nothing) if it now costs more than the estimate
 deepsieve runs list
 deepsieve runs get <id>                       # exit 4 while still running
 deepsieve runs cancel <id>
@@ -38,7 +39,11 @@ deepsieve members list                        # who is in the organization + sea
 deepsieve changes list --live                 # merges, renames, successor links
 deepsieve changes undo <id>                   # asks first; --yes in scripts
 deepsieve merge preview <entity> --survivor <id> --loser <id>   # writes nothing
-deepsieve merge apply <entity> --survivor <id> --loser <id> [--choice KEY=loser]
+deepsieve merge apply <entity> --survivor <id> --loser <id> [--choice KEY=loser] --preview-digest <digest>
+deepsieve runs retry <id>                     # a retry that charges shows its total and asks
+deepsieve runs reruns <id>                    # a report's re-research waiting for approval
+deepsieve runs monitoring <id> --off          # stop a report's monitoring; asks first
+deepsieve links remove <entity> <record-id> <linked-entity> <target-id>   # asks first
 deepsieve data catalog                        # entities + columns (never guess)
 deepsieve data get companies --receipts       # rows with per-cell citations
 deepsieve chat thread <run-id>                # changes, with status + warnings

{deepsieve_cli-0.5.0 → deepsieve_cli-0.6.0}/README.md

@@ -23,6 +23,7 @@ deepsieve whoami                              # identity, organization, active B
 deepsieve runs create --query "..." --dry-run # free simulated run (~15s)
 deepsieve runs create --blueprint <id> --query "..." --wait  # real run: spends credits
 deepsieve runs create --blueprint <id> --seeds "..." --allowed-source "*.gov"  # only cite these
+deepsieve runs create --blueprint <id> --query "..." --expected-total 1000  # refuse (charge nothing) if it now costs more than the estimate
 deepsieve runs list
 deepsieve runs get <id>                       # exit 4 while still running
 deepsieve runs cancel <id>
@@ -30,7 +31,11 @@ deepsieve members list                        # who is in the organization + sea
 deepsieve changes list --live                 # merges, renames, successor links
 deepsieve changes undo <id>                   # asks first; --yes in scripts
 deepsieve merge preview <entity> --survivor <id> --loser <id>   # writes nothing
-deepsieve merge apply <entity> --survivor <id> --loser <id> [--choice KEY=loser]
+deepsieve merge apply <entity> --survivor <id> --loser <id> [--choice KEY=loser] --preview-digest <digest>
+deepsieve runs retry <id>                     # a retry that charges shows its total and asks
+deepsieve runs reruns <id>                    # a report's re-research waiting for approval
+deepsieve runs monitoring <id> --off          # stop a report's monitoring; asks first
+deepsieve links remove <entity> <record-id> <linked-entity> <target-id>   # asks first
 deepsieve data catalog                        # entities + columns (never guess)
 deepsieve data get companies --receipts       # rows with per-cell citations
 deepsieve chat thread <run-id>                # changes, with status + warnings

{deepsieve_cli-0.5.0 → deepsieve_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepsieve-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "DeepSieve CLI — run cited deep research from your terminal"
 requires-python = ">=3.11"
 readme = "README.md"

{deepsieve_cli-0.5.0 → deepsieve_cli-0.6.0}/src/deepsieve_cli/main.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import math
 import os
 import re
 import sys
@@ -266,6 +267,15 @@ def cmd_runs_get(args) -> int:
     return EXIT_OK if body.get("status") == "completed" else EXIT_FAIL
 
 
+def _folded_text(folds: list[dict]) -> str:
+    """gh #2716 — the seeds a request counted once, in one line (the first 4, then a count)."""
+    if not folds:
+        return ""
+    shown = ", ".join(f'"{f.get("seed")}" as "{f.get("kept_as")}"' for f in folds[:4])
+    more = f" and {len(folds) - 4} more" if len(folds) > 4 else ""
+    return f"{len(folds)} counted once: {shown}{more}."
+
+
 def cmd_runs_create(args) -> int:
     client, prof = _require_auth(args)
     # At most one. NEITHER is a paid broad sweep of the whole Blueprint schema
@@ -291,8 +301,15 @@ def cmd_runs_create(args) -> int:
         # #1802 — repeatable; the server resolves and refuses, the CLI only carries.
         # Only blanks given → no list at all, never an empty one (the server 400s on []).
         body["allowed_sources"] = allowed
+    excluded = [s.strip() for s in (getattr(args, "excluded_source", None) or []) if s.strip()]
+    if excluded:
+        # gh #2641 — repeatable; the server resolves and refuses, the CLI only carries.
+        body["excluded_sources"] = excluded
     if getattr(args, "blueprint", None):
         body["blueprint_id"] = args.blueprint
+    if getattr(args, "expected_total", None) is not None:
+        # gh #2710 — bind the run to the estimate: a higher total is refused, never charged.
+        body["expected_total_cents"] = args.expected_total
 
     # A real run spends money. Confirm interactively unless told not to — and
     # never silently in a pipe, where nobody is watching.
@@ -317,6 +334,17 @@ def cmd_runs_create(args) -> int:
             headers={"Idempotency-Key": args.idempotency_key or uuid.uuid4().hex},
         )
     except ApiError as exc:
+        if exc.code == "run_price_changed":
+            # gh #2710 — the run would now cost more than --expected-total. Nothing was charged.
+            total = exc.details.get("total_price_cents")
+            if isinstance(total, int) and not isinstance(total, bool):
+                ask = (f"The price for this run changed since it was estimated: it is now "
+                       f"${total / 100:,.2f}. Nothing was charged.")
+                if args.json:
+                    print(json.dumps({"error": {"code": exc.code, "message": ask,
+                                                "details": exc.details}}))
+                err(f"{ask} Pass --expected-total {total} to start at the new price.")
+                return EXIT_USAGE
         err(str(exc))
         # A --query is parsed by a model: the org's model allowance can refuse it (gh #2307).
         return _api_exit(exc)
@@ -326,6 +354,9 @@ def cmd_runs_create(args) -> int:
         return EXIT_OK
     run_id = created.get("id")
     print(f"started run {run_id} ({'dry run' if args.dry_run else 'billable'})")
+    folded = _folded_text(created.get("folded_duplicates") or [])
+    if folded:
+        print(folded)
     bp = created.get("blueprint") or {}
     if bp:
         print(f"Blueprint: {bp.get('name')} ({bp.get('id')})")
@@ -472,6 +503,288 @@ def cmd_runs_monitoring(args) -> int:
     return EXIT_OK
 
 
+def _reruns_summary(rid: str, v: dict) -> str:
+    waiting = v.get("awaiting_count") or 0
+    lines = [
+        f"{waiting} waiting for re-research on {rid}"
+        + (f", {_usd(v.get('awaiting_total_cents') or 0)} to approve now" if waiting else "")
+    ]
+    for it in v.get("items") or []:
+        what = it.get("column_label") or it.get("column") or "a fact"
+        who = it.get("entity") or "an entity"
+        lines.append(f"  - {who}" + (f", for {it['child']}" if it.get("child") else "") + f": {what}")
+    if waiting > len(v.get("items") or []):
+        lines.append(f"  … and {waiting - len(v.get('items') or [])} more")
+    if v.get("quote_withheld"):
+        lines.append(v["quote_withheld"])
+    lines.append(
+        f"included this period: {v.get('included_used', 0)}/{v.get('included_per_period', 0)}; "
+        f"renews {v.get('next_period_start') or 'unknown'}"
+    )
+    if v.get("auto_approve"):
+        lines.append(
+            f"auto-approve ON, up to {_usd(v.get('auto_approve_cap_cents') or 0)}/month "
+            f"({_usd(v.get('auto_approve_spent_cents') or 0)} spent)"
+        )
+    return "\n".join(lines)
+
+
+#: The API's ceiling on a monthly auto-approve cap, in cents (`maximum` in the contract; the
+#: column is a Postgres INTEGER). Checked here so the CLI refuses before it asks.
+_AUTO_APPROVE_CAP_MAX_CENTS = 2_147_483_647
+
+
+def cmd_runs_reruns(args) -> int:
+    """A report's re-research waiting for approval (gh #2351): show it, approve it, or turn
+    auto-approve on or off. Approving SPENDS money: it needs --expected-total and --quote-id (both
+    from what you were shown), or an interactive yes to what was fetched just now; never a silent
+    yes in a pipe. The quote pins the exact rows, so an approval never buys a rerun you were not
+    shown. There is no decline: a rerun left waiting costs nothing and is decided again at
+    renewal.
+
+    Turning auto-approve ON (gh #2506) is standing authority to spend on this report's future
+    re-research, up to a monthly limit you must give (--cap, in dollars). It is recorded against
+    the key or app you are signed in with: it switches off if that key is revoked or expires, or
+    you sign out everywhere, and pauses while the key is suspended. Confirmed like approving:
+    interactively, or with --yes, never silently in a pipe."""
+    rid = _uuid_arg(args.run_id, "run_id")
+    if rid is None:
+        return EXIT_USAGE
+    client, _ = _require_auth(args)
+    base = f"/v1/research/runs/{rid}/reruns"
+    if not args.auto_approve_on and (args.cap is not None or args.yes):
+        # seat-2506b F5: these belong to --auto-approve-on alone; silently ignoring them let a
+        # user believe --yes had confirmed something else.
+        err("--cap and --yes go with --auto-approve-on")
+        return EXIT_USAGE
+    try:
+        if args.auto_approve_on:
+            # seat-2506b F3/F4: a cap that is not a finite number, or that rounds to less than
+            # the API's 1 cent, is refused here (it used to traceback, or confirm "$0.00").
+            cap_ok = args.cap is not None and math.isfinite(args.cap) and args.cap > 0
+            cap_cents = int(round(args.cap * 100)) if cap_ok else 0
+            if cap_cents < 1 or cap_cents > _AUTO_APPROVE_CAP_MAX_CENTS:
+                err(
+                    "turning auto-approve on needs --cap USD: the most it may spend a month, "
+                    f"from $0.01 to {_usd(_AUTO_APPROVE_CAP_MAX_CENTS)}"
+                )
+                return EXIT_USAGE
+            what = (
+                f"Turn on auto-approve for {rid}? Its future re-research is approved and charged "
+                f"automatically, up to {_usd(cap_cents)} a month. It switches off if the key or "
+                "app you are signed in with is revoked."
+            )
+            if not args.yes:
+                if not _interactive():
+                    err("refusing to turn on auto-approve non-interactively (it spends money); "
+                        "pass --yes")
+                    return EXIT_USAGE
+                if not _yes(f"{what} [y/N] "):
+                    print("Cancelled. Auto-approve was not changed.")
+                    return EXIT_OK
+            body = client.request(
+                "PATCH",
+                f"{base}/auto-approve",
+                json_body={"auto_approve": True, "auto_approve_cap_cents": cap_cents},
+            )
+            out(body, args.json, _reruns_summary(rid, body))
+            return EXIT_OK
+        if args.auto_approve_off:
+            body = client.request("PATCH", f"{base}/auto-approve", json_body={"auto_approve": False})
+            out(body, args.json, _reruns_summary(rid, body))
+            return EXIT_OK
+        if not args.approve:
+            body = client.request("GET", base)
+            out(body, args.json, _reruns_summary(rid, body))
+            return EXIT_OK
+        total, quote_id = args.expected_total, args.quote_id
+        if total is None or not quote_id:
+            if not _interactive():
+                err("approving spends money: pass --expected-total CENTS and --quote-id ID "
+                    "(both from `deepsieve runs reruns RID --json`)")
+                return EXIT_USAGE
+            state = client.request("GET", base)
+            print(_reruns_summary(rid, state))
+            total = int(state.get("awaiting_total_cents") or 0)
+            quote_id = state.get("quote_id") or ""
+            if not state.get("awaiting_count"):
+                print("Nothing is waiting.")
+                return EXIT_OK
+            if not quote_id:
+                # gh #2351 delta review: past what the API will list there is no quote, and asking
+                # "Approve N?" over rows the list could not show is asking for a blind yes.
+                err("these cannot be approved here (the reason is above). Nothing was charged.")
+                return EXIT_USAGE
+            if not _yes(f"Approve {state['awaiting_count']} for {_usd(total)}? [y/N] "):
+                print("Cancelled. Nothing was charged.")
+                return EXIT_OK
+        body = client.request(
+            "POST",
+            f"{base}/approve",
+            json_body={"expected_total_cents": total, "quote_id": quote_id},
+            headers={"Idempotency-Key": uuid.uuid4().hex},
+        )
+    except ApiError as exc:
+        if exc.code == "rerun_price_changed":
+            if not (exc.details or {}).get("count"):
+                err("nothing is waiting any more (it was approved, or retired). Nothing was charged.")
+            else:
+                err(
+                    f"what is waiting changed: {exc.details['count']} now, costing "
+                    f"{_usd(exc.details.get('total_cents') or 0)}. "
+                    "Nothing was charged; run it again to see the new list."
+                )
+        else:
+            err(str(exc))
+        return _api_exit(exc)
+    human = f"approved {body.get('approved', 0)} for {rid}; {body.get('still_waiting', 0)} still waiting"
+    if body.get("stopped"):
+        human += f"\nstopped part-way: {body['stopped']}"
+    out(body, args.json, human)
+    return EXIT_OK
+
+
+def _usd(cents) -> str:
+    return f"${cents / 100:,.2f}"
+
+
+def _refund_line(refund: dict | None) -> str:
+    """What became of the earlier run's charge (gh #2389), in the app's words (site
+    `refundHeadline`), so the CLI and the Retry dialog never state it differently."""
+    refund = refund or {}
+    status, kind = refund.get("run_status"), refund.get("kind")
+    run = {"failed": "failed run", "cancelled": "stopped run"}.get(status, "earlier run")
+    amount, credits, units = refund.get("amount_cents"), refund.get("credits"), refund.get("units")
+    plural = lambda n, one, many: f"{n} {one if n == 1 else many}"  # noqa: E731
+    if kind == "refunded_dollars":
+        return (f"Your {run} was refunded. {_usd(amount)} is back on your account."
+                if amount is not None else f"Your {run} was refunded in full.")
+    if kind == "refunded_free_run":
+        return f"Your {run} was refunded. Your free run is back."
+    if kind == "refunded_credits":
+        return (f"Your {run} was refunded. {plural(credits, 'run credit is', 'run credits are')} back."
+                if credits is not None else f"Your {run} was refunded. Its run credits are back.")
+    if kind == "allowance_restored":
+        return (f"Your {run} didn't fully count. {plural(units, 'included rerun is', 'included reruns are')} back."
+                if units is not None else f"Your {run} didn't count. Its included rerun is back.")
+    if kind == "not_charged":
+        return f"Your {run} wasn't charged."
+    if kind == "kept_free_run":
+        if status in ("completed", None):
+            return ("Your earlier run used your free run. It finished with no results, and a "
+                    "finished run isn't refunded.")
+        return f"Your {run} used your free run. Part of it returned results, so your free run stays used."
+    if kind == "kept_credits":
+        used = plural(credits, "run credit", "run credits") if credits is not None else "run credits"
+        return f"Your earlier run used {used}. It finished with no results, and a finished run isn't refunded."
+    if kind == "refunded_to_ended_plan":
+        return f"Your plan has ended, so the credits for your {run} were returned to it and can't be used."
+    if kind == "refunded_to_ended_period":
+        # gh #2460: the plan is still running; an earlier billing period's allowance ended.
+        return (f"The credits for your {run} went back to the billing period they came from, "
+                "which has ended, so they can't be used again.")
+    if kind == "refunded_unknown":
+        return f"Your {run} was refunded in full."
+    if kind == "refund_pending":
+        return f"Your {run} is being refunded."
+    if kind == "partially_refunded":
+        lead = f"Part of your {run} returned nothing, and that part was refunded."
+        if amount is not None:
+            return f"{lead} {_usd(amount)} is back on your account."
+        if credits is not None:
+            return f"{lead} {plural(credits, 'run credit is', 'run credits are')} back."
+        return lead
+    return "We can't confirm yet whether your earlier run was refunded. We're checking it."
+
+
+def _retry_cost(details: dict) -> str:
+    """What would pay, from the quote's `funding` (seat-2389 M3): `total_price_cents` is the
+    LIST price even when the free run or plan credits cover the retry."""
+    total = details.get("total_price_cents")
+    funding = details.get("funding") or {}
+    if funding.get("covered_by") == "free_run":
+        return f"uses your free run (list price {_usd(total)})"
+    if funding.get("covered_by") == "plan_credits":
+        n = funding.get("plan_credits_needed")
+        return f"uses {n} plan run credit{'' if n == 1 else 's'} (list price {_usd(total)})"
+    cost = f"charges {_usd(total)}"
+    if (details.get("shortfall_cents") or 0) > 0:
+        cost += f", and your balance is {_usd(details['shortfall_cents'])} short"
+    return cost
+
+
+def _retry_quote_text(details: dict, moved: bool) -> str:
+    parts = [
+        "The price changed since the quote." if moved else "",
+        _refund_line(details.get("refund")),
+        f"Retrying starts a new run and {_retry_cost(details)}.",
+    ]
+    for key, what in (
+        ("reuse_predicted", "carried over at no charge"),
+        ("skipped_already_held", "already in the report, skipped"),
+    ):
+        names = details.get(key) or []
+        if names:
+            parts.append(f"{len(names)} {what}: {', '.join(names[:4])}"
+                         + (f" and {len(names) - 4} more" if len(names) > 4 else "") + ".")
+    return " ".join(p for p in parts if p)
+
+
+def cmd_runs_retry(args) -> int:
+    """Retry a failed, stopped or empty run, as the app's Retry does (gh #2389).
+
+    A retry that charges nothing starts at once. A retry that will CHARGE is refused by the API
+    (`retry_confirmation_required`) until it is sent with the total it was quoted: here, an
+    explicit question showing the refund and the total, or --expected-total CENTS. In a pipe it
+    never confirms by itself. A price that moved meanwhile (`retry_price_changed`) is asked again
+    with the new total; nothing is charged in between."""
+    rid = _uuid_arg(args.run_id, "run_id")
+    if rid is None:
+        return EXIT_USAGE
+    client, _ = _require_auth(args)
+    path = f"/v1/research/runs/{rid}/retry"
+    payload: dict = {}
+    if args.expected_total is not None:
+        payload["expected_total_cents"] = args.expected_total
+    # At most two refusals: the quote, and one re-quote if the price moved while the person was
+    # deciding. A third would be the API contradicting itself; stop rather than loop, and never ask
+    # a question whose yes would not be sent (seat-2389 L1).
+    attempts = 3
+    body = None
+    for attempt in range(attempts):
+        try:
+            body = client.request("POST", path, json_body=payload)
+            break
+        except ApiError as exc:
+            if exc.code not in ("retry_confirmation_required", "retry_price_changed"):
+                err(str(exc))
+                return _api_exit(exc)
+            total = exc.details.get("total_price_cents")
+            if not isinstance(total, int) or isinstance(total, bool):
+                # No quote to state: never prompt "$0.00" (seat-2389 L2).
+                err(f"{exc} (the API sent no total to confirm; nothing was charged)")
+                return EXIT_FAIL
+            ask = _retry_quote_text(exc.details, moved=exc.code == "retry_price_changed")
+            if not _interactive():
+                if args.json:
+                    print(json.dumps({"error": {"code": exc.code, "message": ask, "details": exc.details}}))
+                err(f"{ask} Pass --expected-total {total} to confirm that charge.")
+                return EXIT_USAGE
+            if attempt == attempts - 1:
+                break  # the last refusal: no request would follow, so ask nothing
+            if not _yes(f"{ask} Retry at {_usd(total)}? [y/N] "):
+                print("Cancelled. Nothing was charged.")
+                return EXIT_OK
+            payload = {"expected_total_cents": total}
+    if body is None:
+        err("the API kept refusing the confirmation; nothing was charged")
+        return EXIT_FAIL
+    retry = body.get("retry") or {}
+    how = "resumed" if retry.get("mode") == "resumed" else f"restarted as {body.get('id')}"
+    out(body, args.json, f"retry of {rid} {how}")
+    return EXIT_OK
+
+
 def _uuid_arg(value: str, what: str) -> str | None:
     """An id interpolated into a URL path must be a UUID, never a path fragment."""
     import uuid as _uuid  # noqa: PLC0415
@@ -577,6 +890,9 @@ def _describe_change(c: dict) -> str:
         return f"renamed {c.get('old_name')} to {c.get('new_name')}"
     if kind == "succeeded_by":
         return f"{c.get('old_name')} succeeded by {c.get('new_name')}"
+    if kind == "link_removed":
+        link = c.get("link") or {}
+        return f"removed {link.get('target_name') or link.get('target_id')} from {link.get('record_name')}"
     return str(kind)
 
 
@@ -785,10 +1101,15 @@ def _print_merge(body: dict) -> None:
     if ties:
         print(f"\nopen ties ({len(ties)}): settle each with --choice KEY=survivor|loser, "
               "or pass --accept-survivor-on-ties")
+    # #2409: the apply confirms THIS merge by its digest; a merge that changed since is refused.
+    if body.get("preview_digest") and not body.get("applied"):
+        print(f"\nto apply exactly this merge: --preview-digest {body['preview_digest']}")
 
 
 #: Merge refusals fixed by changing the command, not by retrying: exit 2, not 1.
-_MERGE_USAGE_CODES = frozenset({"ties_unresolved", "merge_across_parents"})
+_MERGE_USAGE_CODES = frozenset(
+    {"ties_unresolved", "merge_across_parents", "merge_changed", "preview_required"}
+)
 
 
 def cmd_merge_preview(args) -> int:
@@ -817,6 +1138,15 @@ def cmd_merge_apply(args) -> int:
     if body is None:
         return EXIT_USAGE
     body["accept_survivor_on_ties"] = bool(args.accept_survivor_on_ties)
+    # #2409: confirm the merge you previewed, or say you are merging blind. Neither is refused by
+    # the API (preview_required); both is a contradiction, refused here before any call.
+    if args.preview_digest and args.without_preview:
+        err("pass --preview-digest or --without-preview, not both")
+        return EXIT_USAGE
+    if args.preview_digest:
+        body["preview_digest"] = args.preview_digest
+    if args.without_preview:
+        body["apply_without_preview"] = True
     if not args.yes:
         if not _interactive():
             err("refusing to change data non-interactively; pass --yes")
@@ -830,6 +1160,14 @@ def cmd_merge_apply(args) -> int:
         out_ = client.request("POST", "/v1/merges", json_body=body, headers=headers)
     except ApiError as exc:
         err(str(exc))
+        if exc.code == "merge_changed" and exc.details.get("preview"):
+            # #2409: what the merge would do NOW, so the person sees what moved. Under --json it
+            # stays JSON on stdout (seat-2409 5c): a script parses it, never human text.
+            if args.json:
+                out(exc.details["preview"], True)
+            else:
+                print("\nthe merge as it stands now:")
+                _print_merge(exc.details["preview"])
         # An open tie is fixed by changing the command (--choice, or
         # --accept-survivor-on-ties), so it exits as a usage error: a script can tell it
         # apart from a failure without --json. So is a merge across parents (#2254): no retry
@@ -843,6 +1181,47 @@ def cmd_merge_apply(args) -> int:
     return EXIT_OK
 
 
+def cmd_links_remove(args) -> int:
+    """Remove one many-to-many link from a record (gh #2514). Research does not add it back.
+    It changes the dataset, so it is confirmed like a merge: interactively, or with --yes,
+    never silently in a pipe. Undo it with `deepsieve changes undo <change id>`."""
+    client, _ = _require_auth(args)
+    for value, name in ((args.record_id, "record id"), (args.target_id, "target id")):
+        try:
+            uuid.UUID(value)
+        except ValueError:
+            err(f"{name} must be a UUID")
+            return EXIT_USAGE
+    body = {
+        "entity": args.entity,
+        "record_id": args.record_id,
+        "to_entity": args.to_entity,
+        "target_id": args.target_id,
+    }
+    if args.blueprint:
+        body["blueprint_id"] = args.blueprint
+    if not args.yes:
+        if not _interactive():
+            err("refusing to change data non-interactively; pass --yes")
+            return EXIT_USAGE
+        prompt = (
+            f"Remove the {args.to_entity} link {args.target_id} from {args.entity} "
+            f"{args.record_id}? Research will not add it back. [y/N] "
+        )
+        if input(prompt).strip().lower() not in ("y", "yes"):
+            print("Cancelled.")
+            return EXIT_OK
+    headers = {"Idempotency-Key": args.idempotency_key} if args.idempotency_key else None
+    try:
+        out_ = client.request("POST", "/v1/links/remove", json_body=body, headers=headers)
+    except ApiError as exc:
+        err(str(exc))
+        return _api_exit(exc)
+    human = f"{_describe_change(out_)}. Undo: deepsieve changes undo {out_.get('change_id')}"
+    out(out_, args.json, human)
+    return EXIT_OK
+
+
 def _blueprint_id(client, args) -> str | None:
     """The Blueprint these commands address: ``--blueprint``, else the active one.
 
@@ -1146,6 +1525,9 @@ def build_parser() -> argparse.ArgumentParser:
                     help="restrict evidence to this source (repeatable): a host, *.gov, "
                          "https://host/path/*, or blueprint:primary; a cell cited only "
                          "elsewhere is not written")
+    rc.add_argument("--excluded-source", action="append", metavar="PATTERN",
+                    help="never cite this source (repeatable): a host, *.tld or "
+                         "https://host/path/*; a citation on it is not written")
     rc.add_argument("--blueprint", help="Blueprint id to research; REQUIRED unless --dry-run "
                     "(`deepsieve whoami` shows your active Blueprint's id)")
     rc.add_argument("--depth", default="standard", choices=["standard", "max"])
@@ -1157,6 +1539,13 @@ def build_parser() -> argparse.ArgumentParser:
     rc.add_argument("--timeout", type=int, default=3600)
     rc.add_argument("--idempotency-key")
     rc.add_argument("-y", "--yes", action="store_true", help="skip the billable-run confirmation")
+    rc.add_argument(
+        "--expected-total",
+        type=int,
+        default=None,
+        metavar="CENTS",
+        help="the estimate's run_price_cents: refuse (and charge nothing) if the run now costs more",
+    )
     rc.set_defaults(func=cmd_runs_create)
 
     rw = runs.add_parser("wait", help="poll an existing run to completion", parents=[common])
@@ -1169,6 +1558,21 @@ def build_parser() -> argparse.ArgumentParser:
     rx.add_argument("run_id")
     rx.set_defaults(func=cmd_runs_cancel)
 
+    rr = runs.add_parser(
+        "retry",
+        help="retry a failed, stopped or empty run (a retry that charges asks first)",
+        parents=[common],
+    )
+    rr.add_argument("run_id")
+    rr.add_argument(
+        "--expected-total",
+        type=int,
+        default=None,
+        metavar="CENTS",
+        help="confirm a charging retry at the total you were quoted, in cents",
+    )
+    rr.set_defaults(func=cmd_runs_retry)
+
     rm = runs.add_parser(
         "monitoring",
         help="turn a report's monitoring on or off (ON bills daily past the free 30 days)",
@@ -1191,6 +1595,37 @@ def build_parser() -> argparse.ArgumentParser:
     )
     rm.set_defaults(func=cmd_runs_monitoring)
 
+    rq = runs.add_parser(
+        "reruns",
+        help="a report's re-research waiting for approval: show, --approve (spends), or "
+        "--auto-approve-on/--auto-approve-off",
+        parents=[common],
+    )
+    rq.add_argument("run_id")
+    act = rq.add_mutually_exclusive_group()
+    act.add_argument("--approve", action="store_true", help="approve everything waiting (spends money)")
+    rq.add_argument(
+        "--expected-total",
+        type=int,
+        default=None,
+        metavar="CENTS",
+        help="with --approve: the total you were shown, in cents; refused if the price moved. "
+        "Without --quote-id it is ignored: in a terminal the list and total are fetched and you "
+        "confirm those",
+    )
+    rq.add_argument("--quote-id", default="", metavar="ID",
+                    help="with --approve: the quote_id you were shown; refused if what is waiting changed")
+    act.add_argument("--auto-approve-off", action="store_true",
+                     help="stop approving this report's future re-research automatically")
+    act.add_argument("--auto-approve-on", action="store_true",
+                     help="approve this report's future re-research automatically, up to --cap a "
+                     "month (spends money; it switches off if your key is revoked)")
+    rq.add_argument("--cap", type=float, default=None, metavar="USD",
+                    help="with --auto-approve-on: the most it may spend a month, in dollars (required)")
+    rq.add_argument("--yes", action="store_true",
+                    help="with --auto-approve-on: do not ask for confirmation (required in a pipe)")
+    rq.set_defaults(func=cmd_runs_reruns)
+
     chat = sub.add_parser("chat", help="a run's chat and the changes it proposed", parents=[common]).add_subparsers(dest="sub", required=True)
     ct = chat.add_parser("thread", help="the thread, with each change's status and warnings", parents=[common])
     ct.add_argument("run_id")
@@ -1208,10 +1643,10 @@ def build_parser() -> argparse.ArgumentParser:
     ml = members.add_parser("list", help="who is in the organization, and seat usage", parents=[common])
     ml.set_defaults(func=cmd_members_list)
 
-    changes = sub.add_parser("changes", help="merges, renames and successor links", parents=[common]).add_subparsers(dest="sub", required=True)
+    changes = sub.add_parser("changes", help="merges, renames, successor links and removed links", parents=[common]).add_subparsers(dest="sub", required=True)
     cl = changes.add_parser("list", help="newest first; undone ones included unless --live", parents=[common])
     cl.add_argument("--entity", help="only this entity's records (an entity key)")
-    cl.add_argument("--kind", choices=["merge", "renamed", "succeeded_by"])
+    cl.add_argument("--kind", choices=["merge", "renamed", "succeeded_by", "link_removed"])
     cl.add_argument("--by", choices=["user", "automatic", "operator"], help="who made the change")
     cl.add_argument("--live", action="store_true", help="leave out undone changes")
     cl.add_argument("--limit", type=int, default=25)
@@ -1226,6 +1661,17 @@ def build_parser() -> argparse.ArgumentParser:
                     help="undo a merge even though cells it filled changed since")
     cu.set_defaults(func=cmd_changes_undo)
 
+    links = sub.add_parser("links", help="a record's many-to-many links", parents=[common]).add_subparsers(dest="sub", required=True)
+    lr = links.add_parser("remove", help="remove one link; research will not add it back (needs data:write)", parents=[common])
+    lr.add_argument("entity", help="the entity whose record lists the link (an entity key)")
+    lr.add_argument("record_id")
+    lr.add_argument("to_entity", help="the linked entity")
+    lr.add_argument("target_id", help="the linked record to remove")
+    lr.add_argument("--blueprint", help="Blueprint id (default: the active one)")
+    lr.add_argument("--yes", action="store_true", help="do not ask for confirmation")
+    lr.add_argument("--idempotency-key", help="make a retry safe")
+    lr.set_defaults(func=cmd_links_remove)
+
     holds = sub.add_parser("holds", help="cells you set on purpose, and newer research", parents=[common]).add_subparsers(dest="sub", required=True)
     hl = holds.add_parser("list", help="newest first; --pending for those with newer research", parents=[common])
     hl.add_argument("--entity", help="only this entity's cells (an entity key)")
@@ -1268,6 +1714,10 @@ def build_parser() -> argparse.ArgumentParser:
                             help="keep the survivor's value on every tie you did not settle")
             mp.add_argument("--yes", action="store_true", help="do not ask for confirmation")
             mp.add_argument("--idempotency-key", help="make a retry safe")
+            mp.add_argument("--preview-digest", metavar="DIGEST",
+                            help="apply exactly the merge `merge preview` showed (its digest)")
+            mp.add_argument("--without-preview", action="store_true",
+                            help="merge without confirming a preview (a blind merge, on purpose)")
         mp.set_defaults(func=func)
 
     data = sub.add_parser("data", help="your cited dataset", parents=[common]).add_subparsers(dest="sub", required=True)

{deepsieve_cli-0.5.0 → deepsieve_cli-0.6.0}/tests/test_cli.py

@@ -253,6 +253,61 @@ def test_run_create_with_neither_sends_an_empty_broad_sweep(monkeypatch):
     assert seen["body"]["dry_run"] is True
 
 
+def test_run_create_sends_the_expected_total_only_when_given(monkeypatch):
+    """gh #2710: --expected-total binds the create to the estimate; without it, no field."""
+    cfg.save_profile(cfg.Profile(name="default", origin="https://x.test", api_key="k"))
+    bodies = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        bodies.append(json.loads(request.content))
+        return httpx.Response(202, json={"id": "run_1", "status": "queued"})
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    base = ["runs", "create", "--seeds", "Acme", "--blueprint", "bp-a", "--yes"]
+    assert main(base) == 0
+    assert main([*base, "--expected-total", "1000"]) == 0
+    assert "expected_total_cents" not in bodies[0]
+    assert bodies[1]["expected_total_cents"] == 1000
+
+
+def test_run_create_that_now_costs_more_says_the_new_total_and_charges_nothing(
+    monkeypatch, capsys
+):
+    """gh #2710: a 409 run_price_changed prints the new total and the flag to resend with, and
+    exits as a usage refusal (the human decides), never as a started run."""
+    cfg.save_profile(cfg.Profile(name="default", origin="https://x.test", api_key="k"))
+    monkeypatch.setattr("deepsieve_cli.main._tty", lambda: False)
+    refusal = {
+        "error": {
+            "type": "conflict_error",
+            "code": "run_price_changed",
+            "message": "The price for this run changed since it was estimated.",
+            "param": "expected_total_cents",
+            "retriable": False,
+            "details": {
+                "expected_total_cents": 1000,
+                "total_price_cents": 2000,
+                "interactions": 2,
+                "unit_price_cents": 1000,
+            },
+        }
+    }
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(409, json=refusal)
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    code = main(
+        ["runs", "create", "--seeds", "Acme", "--blueprint", "bp-a", "--yes",
+         "--expected-total", "1000"]
+    )
+    err = capsys.readouterr().err
+    print("exit", code, "err", err)
+    assert code == 2
+    assert "it is now $20.00. Nothing was charged." in err
+    assert "Pass --expected-total 2000 to start at the new price." in err
+
+
 # A workspace with one Blueprint, active. `data` commands resolve through this
 # listing since #1282 removed the ambient /v1/data — so a handler that does not
 # serve it is a handler the data commands cannot get past.
@@ -360,6 +415,12 @@ def test_unfinished_run_exits_pending(monkeypatch):
         ["merge", "preview", "books", "--survivor", "s", "--loser", "l", "--json"],
         ["merge", "apply", "books", "--survivor", "s", "--loser", "l", "--loser", "m", "--yes"],
         ["changes", "undo", "00000000-0000-0000-0000-000000000000", "--yes"],
+        # #2615: the re-research and link-removal lines cli.md now shows.
+        ["runs", "reruns", "r"],
+        ["runs", "reruns", "r", "--approve", "--expected-total", "900", "--quote-id", "q"],
+        ["runs", "reruns", "r", "--auto-approve-on", "--cap", "50"],
+        ["runs", "reruns", "r", "--auto-approve-off"],
+        ["links", "remove", "funds", "rid", "individuals", "tid"],
     ],
 )
 def test_documented_command_lines_parse(argv):
@@ -696,6 +757,24 @@ def test_run_create_forwards_each_allowed_source(monkeypatch):
     assert "allowed_sources" not in seen["body"]
 
 
+def test_run_create_forwards_each_excluded_source(monkeypatch):
+    """gh #2641 — `--excluded-source` mirrors `--allowed-source`: repeatable, a list, absent
+    when not given (agent parity: every surface that takes one takes the other)."""
+    cfg.save_profile(cfg.Profile(name="default", origin="https://x.test", api_key="k"))
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(202, json={"id": "run_1", "status": "queued"})
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "create", "--seeds", "Acme", "--dry-run",
+                 "--excluded-source", "wikipedia.org", "--excluded-source", " *.example "]) == 0
+    assert seen["body"]["excluded_sources"] == ["wikipedia.org", "*.example"]
+    assert main(["runs", "create", "--seeds", "Acme", "--dry-run"]) == 0
+    assert "excluded_sources" not in seen["body"]
+
+
 def test_run_create_names_the_blueprint_it_sends_and_the_one_it_got(monkeypatch, capsys):
     """gh #1282: `--blueprint` reaches the body, and the Blueprint the run is on is
     printed, so a run on the wrong one is visible at once."""
@@ -1094,7 +1173,8 @@ def test_holds_release_refuses_a_malformed_cell_id_and_sends_nothing(monkeypatch
 
 def test_a_billable_run_without_a_blueprint_is_a_usage_error_before_any_request(monkeypatch, capsys):
     """gh #1282 B1: the API now requires `blueprint_id` on run create; the CLI says so first, with
-    where the id comes from, and sends nothing. A dry run may omit it (the API's own exception)."""
+    where the id comes from, and sends nothing. A dry run may omit it (the API's own exception).
+    """
     cfg.save_profile(cfg.Profile(name="default", origin="https://x.test", api_key="k"))
     monkeypatch.setattr("deepsieve_cli.main._tty", lambda: False)
     sent: list[str] = []
@@ -1280,7 +1360,8 @@ def test_declining_the_lock_sends_nothing_more(monkeypatch, capsys):
 
 def test_a_piped_yes_from_a_terminal_never_commits_30_days(monkeypatch, capsys):
     """gh #2345 review, the seat's exact case: stdout is a terminal, stdin is `yes |`. The gate
-    looked at stdout only, so both questions were answered from the pipe and 30 days committed."""
+    looked at stdout only, so both questions were answered from the pipe and 30 days committed.
+    """
     import io
 
     _signed_in(monkeypatch)
@@ -1358,3 +1439,534 @@ def test_end_of_input_at_the_lock_question_is_a_no_not_a_traceback(monkeypatch,
     monkeypatch.setattr(httpx, "Client", _mock(_lock_handler(seen)))
     assert main(["runs", "monitoring", RUN, "--on"]) == 0
     assert seen == [{"active": True}]
+
+
+# ── runs retry: a charging retry is confirmed by its total (gh #2389) ────────
+
+_RETRY_QUOTE = {
+    "total_price_cents": 1200,
+    "interactions": 2,
+    "unit_price_cents": 600,
+    "shortfall_cents": 0,
+    "entities": ["Acme Corp", "Initech"],
+    "refund": {"kind": "refunded_dollars", "amount_cents": 1200},
+    "max_depth": False,
+    "reuse_predicted": ["Held Co"],
+    "skipped_already_held": [],
+}
+
+
+def _retry_handler(seen: list, *, price: int = 1200):
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content) if request.content else {}
+        seen.append(body)
+        if body.get("expected_total_cents") != price:
+            code = "retry_price_changed" if "expected_total_cents" in body else (
+                "retry_confirmation_required"
+            )
+            return httpx.Response(409, json={"error": {
+                "code": code, "message": "confirm the total", "param": "expected_total_cents",
+                "retriable": False, "details": {**_RETRY_QUOTE, "total_price_cents": price},
+            }})
+        return httpx.Response(202, json={
+            "object": "run", "id": "new-run", "status": "queued",
+            "retry": {"source_run_id": RUN, "mode": "restarted"},
+        })
+
+    return handler
+
+
+def test_a_charging_retry_in_a_pipe_names_the_total_and_charges_nothing(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: False)
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_retry_handler(seen)))
+    assert main(["runs", "retry", RUN]) == 2
+    err_text = capsys.readouterr().err
+    print("refusal:", err_text)
+    assert "$12.00 is back on your account" in err_text and "charges $12.00" in err_text
+    assert "1 carried over at no charge: Held Co" in err_text
+    assert "--expected-total 1200" in err_text
+    assert seen == [{}], "only the unconfirmed call, which charges nothing"
+
+
+def test_expected_total_confirms_in_one_call(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_retry_handler(seen)))
+    assert main(["runs", "retry", RUN, "--expected-total", "1200"]) == 0
+    assert seen == [{"expected_total_cents": 1200}]
+    assert "restarted as new-run" in capsys.readouterr().out
+
+
+def test_interactively_the_yes_is_bound_to_the_total_shown(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    prompts: list = []
+    monkeypatch.setattr("builtins.input", lambda prompt="": prompts.append(prompt) or "y")
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_retry_handler(seen)))
+    assert main(["runs", "retry", RUN]) == 0
+    assert seen == [{}, {"expected_total_cents": 1200}]
+    assert "Retry at $12.00?" in prompts[0]
+
+
+def test_declining_a_charging_retry_sends_nothing_more(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    monkeypatch.setattr("builtins.input", lambda prompt="": "n")
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_retry_handler(seen)))
+    assert main(["runs", "retry", RUN]) == 0
+    assert seen == [{}]
+    assert "Nothing was charged" in capsys.readouterr().out
+
+
+def test_a_moved_price_is_asked_again_with_the_new_total(monkeypatch, capsys):
+    """Quoted at one price, confirmed at an old one: the API answers `retry_price_changed` with
+    the new total; the person is asked again and the new yes is bound to the new total."""
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    prompts: list = []
+    monkeypatch.setattr("builtins.input", lambda prompt="": prompts.append(prompt) or "y")
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_retry_handler(seen, price=1500)))
+    assert main(["runs", "retry", RUN, "--expected-total", "1200"]) == 0
+    assert seen == [{"expected_total_cents": 1200}, {"expected_total_cents": 1500}]
+    assert "price changed" in prompts[0] and "$15.00" in prompts[0]
+
+
+def test_a_retry_refusal_under_json_is_machine_readable(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: False)
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_retry_handler(seen)))
+    assert main(["runs", "retry", RUN, "--json"]) == 2
+    out_json = json.loads(capsys.readouterr().out)
+    assert out_json["error"]["code"] == "retry_confirmation_required"
+    assert out_json["error"]["details"]["total_price_cents"] == 1200
+
+
+def test_a_retry_that_charges_nothing_starts_without_asking(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: False)
+    seen: list = []
+
+    def handler(request):
+        seen.append(json.loads(request.content) if request.content else {})
+        return httpx.Response(202, json={"object": "run", "id": RUN, "status": "running",
+                                         "retry": {"source_run_id": RUN, "mode": "resumed"}})
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "retry", RUN]) == 0
+    assert seen == [{}]
+    assert f"retry of {RUN} resumed" in capsys.readouterr().out
+
+
+def test_retry_refuses_a_run_id_that_is_not_a_uuid(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: seen.append(r) or httpx.Response(500)))
+    assert main(["runs", "retry", "../billing"]) == 2
+    assert seen == []
+
+
+def test_a_price_that_keeps_moving_is_asked_twice_and_never_a_third_time(monkeypatch, capsys):
+    """seat-2389 L1: the third refusal ends the loop without a question whose yes is not sent."""
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    prompts: list = []
+    monkeypatch.setattr("builtins.input", lambda prompt="": prompts.append(prompt) or "y")
+    seen: list = []
+    price = iter([1200, 1300, 1400])
+
+    def handler(request):
+        body = json.loads(request.content) if request.content else {}
+        seen.append(body)
+        now = next(price)
+        return httpx.Response(409, json={"error": {
+            "code": "retry_price_changed" if body else "retry_confirmation_required",
+            "message": "moved", "param": "expected_total_cents", "retriable": False,
+            "details": {**_RETRY_QUOTE, "total_price_cents": now},
+        }})
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "retry", RUN]) == 1
+    print("sent:", seen, "prompts:", len(prompts))
+    assert seen == [{}, {"expected_total_cents": 1200}, {"expected_total_cents": 1300}]
+    assert len(prompts) == 2
+    assert "kept refusing" in capsys.readouterr().err
+
+
+def test_a_quote_without_a_total_is_never_asked_as_zero(monkeypatch, capsys):
+    """seat-2389 L2: no `total_price_cents`, no prompt; never "$0.00"."""
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    prompts: list = []
+    monkeypatch.setattr("builtins.input", lambda prompt="": prompts.append(prompt) or "y")
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: httpx.Response(409, json={"error": {
+        "code": "retry_confirmation_required", "message": "confirm", "retriable": False}})))
+    assert main(["runs", "retry", RUN]) == 1
+    assert prompts == []
+    assert "$0.00" not in capsys.readouterr().err
+
+
+@pytest.mark.parametrize(
+    "refund, words",
+    [
+        ({"kind": "kept_credits", "credits": 2, "run_status": "completed"},
+         "Your earlier run used 2 run credits. It finished with no results"),
+        ({"kind": "refund_pending", "run_status": "failed"}, "Your failed run is being refunded."),
+        ({"kind": "refunded_to_ended_plan", "run_status": "cancelled"},
+         "Your plan has ended, so the credits for your stopped run were returned to it"),
+        ({"kind": "refunded_to_ended_period", "run_status": "failed"},
+         "The credits for your failed run went back to the billing period they came from"),
+        ({"kind": "unconfirmed"}, "We can't confirm yet whether your earlier run was refunded."),
+    ],
+    ids=["kept-credits", "pending", "ended-plan", "ended-period", "unconfirmed"],
+)
+def test_every_refund_kind_reads_in_words_never_its_code(monkeypatch, capsys, refund, words):
+    """seat-2389 L3: the app's sentences (site `refundHeadline`), never a raw enum name."""
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: False)
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: httpx.Response(409, json={"error": {
+        "code": "retry_confirmation_required", "message": "confirm", "retriable": False,
+        "details": {**_RETRY_QUOTE, "refund": refund}}})))
+    main(["runs", "retry", RUN])
+    err_text = capsys.readouterr().err
+    assert words in err_text
+    assert refund["kind"] not in err_text
+
+
+@pytest.mark.parametrize(
+    "funding, cost",
+    [
+        ({"covered_by": "plan_credits", "plan_credits_needed": 2}, "uses 2 plan run credits (list price $12.00)"),
+        ({"covered_by": "free_run"}, "uses your free run (list price $12.00)"),
+        ({"covered_by": "balance"}, "charges $12.00"),
+    ],
+    ids=["plan-credits", "free-run", "balance"],
+)
+def test_the_quote_says_what_pays_not_only_the_list_price(monkeypatch, capsys, funding, cost):
+    """seat-2389 M3: `total_price_cents` is the list price even when credits or the free run
+    cover the retry; the human is told what will actually be spent."""
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: False)
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: httpx.Response(409, json={"error": {
+        "code": "retry_confirmation_required", "message": "confirm", "retriable": False,
+        "details": {**_RETRY_QUOTE, "funding": funding}}})))
+    main(["runs", "retry", RUN])
+    assert f"Retrying starts a new run and {cost}." in capsys.readouterr().err
+
+
+
+# --- gh #2351: runs reruns ---------------------------------------------------------------------
+
+_RERUNS = {
+    "object": "reruns",
+    "run_id": RUN,
+    "awaiting_count": 2,
+    "awaiting_total_cents": 2000,
+    "items": [{"entity": "Acme", "column_label": "HQ city"}, {"entity": "Beta", "column": "ceo"}],
+    "included_per_period": 1,
+    "included_used": 1,
+    "next_period_start": "2026-10-06",
+    "auto_approve": False,
+    "quote_id": "rq_abc",
+}
+
+
+def test_runs_reruns_shows_what_is_waiting(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    seen = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append((request.method, request.url.path))
+        return httpx.Response(200, json=_RERUNS)
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "reruns", RUN]) == 0
+    assert seen == [("GET", f"/v1/research/runs/{RUN}/reruns")]
+    out = capsys.readouterr().out
+    assert "2 waiting" in out and "$20.00" in out and "Acme" in out
+
+
+def test_runs_reruns_approve_sends_the_total_and_a_key(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["method"], seen["path"] = request.method, request.url.path
+        seen["body"] = json.loads(request.content)
+        seen["key"] = request.headers.get("Idempotency-Key")
+        return httpx.Response(200, json={"approved": 1, "still_waiting": 0, "run_ids": []})
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "reruns", RUN, "--approve", "--expected-total", "2000", "--quote-id", "rq_abc"]) == 0
+    assert (seen["method"], seen["path"]) == ("POST", f"/v1/research/runs/{RUN}/reruns/approve")
+    assert seen["body"] == {"expected_total_cents": 2000, "quote_id": "rq_abc"}
+    assert seen["key"], "approving spends money: an Idempotency-Key must be sent"
+
+
+def test_runs_reruns_approve_in_a_pipe_needs_the_total_and_sends_nothing(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._tty", lambda: False)
+    calls = []
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: calls.append(r) or httpx.Response(200)))
+    assert main(["runs", "reruns", RUN, "--approve"]) == 2
+    assert main(["runs", "reruns", RUN, "--approve", "--expected-total", "2000"]) == 2  # no quote
+    assert "--quote-id" in capsys.readouterr().err
+    assert calls == []
+
+
+def test_runs_reruns_turns_auto_approve_on_only_with_a_cap_and_a_yes(monkeypatch, capsys):
+    """gh #2506: an agent may turn auto-approve ON (it lapses when its key is revoked). It is
+    standing authority to spend, so the monthly cap is REQUIRED, and it is confirmed like an
+    approval: interactively or with --yes, never silently in a pipe."""
+    _signed_in(monkeypatch)
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append((request.method, json.loads(request.content)))
+        return httpx.Response(200, json=_RERUNS)
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: False)
+    with pytest.raises(SystemExit):
+        main(["runs", "reruns", RUN, "--approve", "--auto-approve-on"])  # one action at a time
+    assert main(["runs", "reruns", RUN, "--auto-approve-on", "--yes"]) == 2  # no cap
+    assert "--cap" in capsys.readouterr().err
+    assert main(["runs", "reruns", RUN, "--auto-approve-on", "--cap", "50"]) == 2  # a pipe, no yes
+    assert "--yes" in capsys.readouterr().err
+    assert calls == [], "nothing may be sent without a cap and a yes"
+    assert main(["runs", "reruns", RUN, "--auto-approve-on", "--cap", "50", "--yes"]) == 0
+    assert calls == [("PATCH", {"auto_approve": True, "auto_approve_cap_cents": 5000})]
+    assert main(["runs", "reruns", RUN, "--auto-approve-off"]) == 0
+    assert calls[-1] == ("PATCH", {"auto_approve": False})
+
+
+@pytest.mark.parametrize("cap", ["nan", "inf", "1e400", "0.004", "-1", "21474836.48"])
+def test_runs_reruns_refuses_a_cap_the_api_cannot_take_before_asking(monkeypatch, capsys, cap):
+    """seat-2506b F3/F4: a cap that is not a finite number used to traceback, and one that
+    rounds under a cent was confirmed as "$0.00 a month" and then refused by the API. The CLI
+    applies the API's own rule (1 cent to the column's ceiling) before it asks or sends."""
+    _signed_in(monkeypatch)
+    calls, asked = [], []
+    monkeypatch.setattr(
+        httpx, "Client", _mock(lambda r: calls.append(r) or httpx.Response(200, json=_RERUNS))
+    )
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    monkeypatch.setattr("deepsieve_cli.main._yes", lambda prompt: asked.append(prompt) or True)
+    assert main(["runs", "reruns", RUN, "--auto-approve-on", "--cap", cap]) == 2
+    assert calls == [] and asked == [], "it asked or sent for a cap the API refuses"
+    assert "--cap" in capsys.readouterr().err
+
+
+def test_runs_reruns_refuses_cap_or_yes_without_auto_approve_on(monkeypatch, capsys):
+    """seat-2506b F5: --cap and --yes belong to --auto-approve-on; silently ignoring them let a
+    user believe --yes had confirmed an approval."""
+    _signed_in(monkeypatch)
+    calls = []
+    monkeypatch.setattr(
+        httpx, "Client", _mock(lambda r: calls.append(r) or httpx.Response(200, json=_RERUNS))
+    )
+    assert main(["runs", "reruns", RUN, "--cap", "50"]) == 2
+    assert main(["runs", "reruns", RUN, "--approve", "--yes"]) == 2
+    assert calls == []
+    assert "--auto-approve-on" in capsys.readouterr().err
+
+
+def test_runs_reruns_asks_before_turning_auto_approve_on(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append((request.method, json.loads(request.content)))
+        return httpx.Response(200, json=_RERUNS)
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    asked = []
+    monkeypatch.setattr("deepsieve_cli.main._yes", lambda prompt: asked.append(prompt) or False)
+    assert main(["runs", "reruns", RUN, "--auto-approve-on", "--cap", "12.5"]) == 0
+    assert calls == [], "a declined prompt sent something"
+    assert "$12.50 a month" in asked[0] and "revoked" in asked[0]
+
+
+def test_runs_reruns_a_moved_price_says_nothing_was_charged(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            409,
+            json={
+                "error": {
+                    "type": "conflict_error",
+                    "code": "rerun_price_changed",
+                    "message": "moved",
+                    "details": {"total_cents": 3000, "count": 3},
+                }
+            },
+        )
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "reruns", RUN, "--approve", "--expected-total", "2000", "--quote-id", "rq_abc"]) != 0
+    err = capsys.readouterr().err
+    assert "$30.00" in err and "Nothing was charged" in err
+
+
+def test_runs_reruns_past_the_ceiling_refuses_before_asking(monkeypatch, capsys):
+    """gh #2351 delta review: past what the API lists there is no quote. The CLI must say why
+    and stop, never ask "Approve 501?" over rows it could not show (and never POST)."""
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    asked: list = []
+    monkeypatch.setattr("deepsieve_cli.main._yes", lambda prompt: asked.append(prompt) or True)
+    withheld = "501 are waiting; more than 500 can't be approved at once through the API."
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request.method)
+        return httpx.Response(
+            200,
+            json={**_RERUNS, "awaiting_count": 501, "quote_id": None, "quote_withheld": withheld},
+        )
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "reruns", RUN, "--approve"]) == 2
+    captured = capsys.readouterr()
+    assert withheld in captured.out and "Nothing was charged" in captured.err
+    assert asked == [] and calls == ["GET"]
+
+
+def test_runs_reruns_nothing_waiting_any_more_is_said_plainly(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    err_body = {"error": {"code": "rerun_price_changed", "message": "m", "param": "expected_total_cents",
+                          "retriable": False, "details": {"total_cents": 0, "count": 0}}}
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: httpx.Response(409, json=err_body)))
+    assert main(["runs", "reruns", RUN, "--approve", "--expected-total", "2000", "--quote-id", "rq_abc"]) != 0
+    err = capsys.readouterr().err
+    assert "nothing is waiting any more" in err and "$0.00" not in err
+
+
+_LINK = {
+    "object": "change",
+    "id": "11111111-1111-4111-8111-111111111111",
+    "change_id": "11111111-1111-4111-8111-111111111111",
+    "kind": "link_removed",
+    "link": {"record_name": "Growth Fund", "target_name": "Ann", "to_entity": "individuals"},
+}
+
+
+def test_links_remove_confirms_sends_the_link_and_prints_the_undo(monkeypatch, capsys):
+    """gh #2514: it changes data, so it is confirmed like a merge; never silent in a pipe."""
+    _signed_in(monkeypatch)
+    seen = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append((request.method, request.url.path, json.loads(request.content)))
+        return httpx.Response(200, json=_LINK)
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: False)
+    args = ["links", "remove", "funds", RUN, "individuals", RUN]
+    assert main(args) == 2 and seen == [], "a pipe without --yes must not change data"
+    assert main([*args, "--yes"]) == 0
+    assert seen == [("POST", "/v1/links/remove", {
+        "entity": "funds", "record_id": RUN, "to_entity": "individuals", "target_id": RUN})]
+    out = capsys.readouterr().out
+    assert "removed Ann from Growth Fund" in out and "deepsieve changes undo 1111" in out
+
+
+def test_links_remove_refuses_a_bad_id_before_any_request(monkeypatch):
+    _signed_in(monkeypatch)
+    calls = []
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: calls.append(r) or httpx.Response(200)))
+    assert main(["links", "remove", "funds", "nope", "individuals", RUN, "--yes"]) == 2
+    assert calls == []
+
+
+# ── merge: what you previewed is what you get (#2409) ─────────────────────────
+
+
+def test_merge_preview_prints_the_digest_to_apply_exactly_that_merge(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr(
+        httpx, "Client", _mock(lambda r: httpx.Response(200, json=_merge_result(preview_digest="d1")))
+    )
+    assert main(["merge", "preview", "books", "--survivor", _S, "--loser", _L]) == 0
+    assert "--preview-digest d1" in capsys.readouterr().out
+
+
+def test_merge_apply_sends_the_digest_or_the_blind_flag_never_both(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    sent = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        sent.append(json.loads(request.content))
+        return httpx.Response(201, json=_merge_result(applied=True, change_id="c-1", unresolved_ties=[]))
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    base = ["merge", "apply", "books", "--survivor", _S, "--loser", _L, "--yes"]
+    assert main([*base, "--preview-digest", "d1"]) == 0
+    assert sent[-1]["preview_digest"] == "d1" and "apply_without_preview" not in sent[-1]
+    assert main([*base, "--without-preview"]) == 0
+    assert sent[-1]["apply_without_preview"] is True and "preview_digest" not in sent[-1]
+    n = len(sent)
+    assert main([*base, "--preview-digest", "d1", "--without-preview"]) == 2
+    assert len(sent) == n, "a contradiction is refused before any request"
+    assert "not both" in capsys.readouterr().err
+
+
+def test_a_changed_merge_shows_what_it_would_do_now_and_exits_as_usage(monkeypatch, capsys):
+    """The person sees what moved: the refusal's current preview, printed, and exit 2 (fixed by
+    re-checking and re-sending, not by retrying unchanged)."""
+    _signed_in(monkeypatch)
+    now = _merge_result(preview_digest="d2")
+    now["conflicts"][0] |= {"survivor_value": "Cat"}
+    body = {"error": {"type": "conflict_error", "code": "merge_changed", "retriable": False,
+                      "message": "This merge changed since its preview.", "param": "preview_digest",
+                      "details": {"preview": now}}}
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: httpx.Response(409, json=body)))
+    argv = ["merge", "apply", "books", "--survivor", _S, "--loser", _L, "--yes", "--preview-digest", "d1"]
+    assert main(argv) == 2
+    captured = capsys.readouterr()
+    assert "changed since its preview" in captured.err
+    assert "survivor='Cat'" in captured.out and "--preview-digest d2" in captured.out
+
+
+def test_a_changed_merge_under_json_prints_the_current_merge_as_json(monkeypatch, capsys):
+    """seat-2409 5c: --json keeps stdout parseable on merge_changed."""
+    _signed_in(monkeypatch)
+    now = _merge_result(preview_digest="d2")
+    body = {"error": {"type": "conflict_error", "code": "merge_changed", "retriable": False,
+                      "message": "This merge changed since its preview.", "param": "preview_digest",
+                      "details": {"preview": now}}}
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: httpx.Response(409, json=body)))
+    argv = ["merge", "apply", "books", "--survivor", _S, "--loser", _L, "--yes",
+            "--preview-digest", "d1", "--json"]
+    assert main(argv) == 2
+    printed = json.loads(capsys.readouterr().out)
+    assert printed["preview_digest"] == "d2"
+
+
+def test_run_create_says_which_seeds_were_counted_once(monkeypatch, capsys):
+    """gh #2716 — the 202's `folded_duplicates` is printed, so a CLI user sees why fewer seeds
+    were researched than were sent; nothing is printed when nothing folded."""
+    cfg.save_profile(cfg.Profile(name="default", origin="https://x.test", api_key="k"))
+    folds = [
+        {"seed": "Fund X, L.P.", "kept_as": "Fund X", "reason": "legal_form"},
+        {"seed": "acme", "kept_as": "Acme", "reason": "case"},
+    ]
+    reply = {"id": "run_1", "status": "queued", "folded_duplicates": folds}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(202, json=reply)
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "create", "--seeds", "Fund X,Fund X, L.P.,Acme,acme", "--dry-run"]) == 0
+    printed = capsys.readouterr().out
+    assert '2 counted once: "Fund X, L.P." as "Fund X", "acme" as "Acme".' in printed
+    reply.pop("folded_duplicates")
+    assert main(["runs", "create", "--seeds", "Fund X", "--dry-run"]) == 0
+    assert "counted once" not in capsys.readouterr().out