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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: deepsieve-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: DeepSieve CLI — run cited deep research from your terminal
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27
@@ -27,14 +27,14 @@ approval screen lists the extra scopes.
 ## Commands
 
 ```bash
-deepsieve whoami                              # identity, workspace, scopes
+deepsieve whoami                              # identity, organization, active Blueprint, scopes
 deepsieve runs create --query "..." --dry-run # free simulated run (~15s)
-deepsieve runs create --query "..." --wait    # real run: spends credits
-deepsieve runs create --seeds "..." --allowed-source "*.gov"  # only cite these
+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 list
 deepsieve runs get <id>                       # exit 4 while still running
 deepsieve runs cancel <id>
-deepsieve members list                        # who is in the workspace + seat usage
+deepsieve members list                        # who is in the organization + seat usage
 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_cli-0.4.0 → deepsieve_cli-0.5.0}/README.md

@@ -19,14 +19,14 @@ approval screen lists the extra scopes.
 ## Commands
 
 ```bash
-deepsieve whoami                              # identity, workspace, scopes
+deepsieve whoami                              # identity, organization, active Blueprint, scopes
 deepsieve runs create --query "..." --dry-run # free simulated run (~15s)
-deepsieve runs create --query "..." --wait    # real run: spends credits
-deepsieve runs create --seeds "..." --allowed-source "*.gov"  # only cite these
+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 list
 deepsieve runs get <id>                       # exit 4 while still running
 deepsieve runs cancel <id>
-deepsieve members list                        # who is in the workspace + seat usage
+deepsieve members list                        # who is in the organization + seat usage
 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_cli-0.4.0 → deepsieve_cli-0.5.0}/pyproject.toml

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

{deepsieve_cli-0.4.0 → deepsieve_cli-0.5.0}/src/deepsieve_cli/client.py

@@ -21,10 +21,19 @@ USER_AGENT = "deepsieve-cli"
 
 
 class ApiError(Exception):
-    def __init__(self, code: str, message: str, *, request_id: str | None = None) -> None:
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        request_id: str | None = None,
+        details: dict | None = None,
+    ) -> None:
         self.code = code
         self.message = message
         self.request_id = request_id
+        #: Structured facts from the error envelope (`locked_until`), when the API sent them.
+        self.details = details or {}
         super().__init__(message)
 
     def __str__(self) -> str:
@@ -87,6 +96,7 @@ class Client:
                 err.get("code", f"http_{r.status_code}"),
                 err.get("message", f"HTTP {r.status_code} from {path}"),
                 request_id=err.get("request_id"),
+                details=err.get("details"),
             )
         return body
 

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

@@ -28,6 +28,14 @@ from . import config
 from .client import ApiError, Client
 
 EXIT_OK, EXIT_FAIL, EXIT_USAGE, EXIT_AUTH, EXIT_PENDING = 0, 1, 2, 3, 4
+#: gh #2307: the organization's model allowance is used for this period. Distinct from a
+#: failure, so a script waits for the reset (or stops) instead of retrying.
+EXIT_LIMIT = 5
+
+
+def _api_exit(exc) -> int:
+    """The exit code for a refused API call."""
+    return EXIT_LIMIT if getattr(exc, "code", None) == "model_allowance_exhausted" else EXIT_FAIL
 
 CLIENT_NAME = "DeepSieve CLI"
 
@@ -36,9 +44,19 @@ CLIENT_NAME = "DeepSieve CLI"
 
 
 def _tty() -> bool:
+    """Whether OUTPUT goes to a terminal (formatting only)."""
     return sys.stdout.isatty()
 
 
+def _interactive() -> bool:
+    """Whether a y/N question can really be put to a person: stdout AND stdin are terminals.
+
+    gh #2345 review: the gate checked stdout only, but every prompt reads stdin, so
+    `yes | deepsieve runs monitoring RID --on` from a terminal answered both questions and
+    committed 30 days of spend. A piped answer is a script, not a person saying yes."""
+    return _tty() and sys.stdin.isatty()
+
+
 def out(data: Any, as_json: bool, human: str | None = None) -> None:
     if as_json or human is None:
         print(json.dumps(data, indent=2, default=str))
@@ -256,6 +274,12 @@ def cmd_runs_create(args) -> int:
     if args.query and args.seeds:
         err("pass at most one of --query or --seeds")
         return EXIT_USAGE
+    # gh #1282 B1: a billable run must NAME its Blueprint (the API refuses one that does not);
+    # say so before anything else, with where the id comes from. A dry run is free and may omit it.
+    if not args.dry_run and not getattr(args, "blueprint", None):
+        err("pass --blueprint <id>: the Blueprint to research. `deepsieve whoami` shows your "
+            "active Blueprint's id (or add --dry-run for a free simulated run)")
+        return EXIT_USAGE
 
     body: dict[str, Any] = {"depth": args.depth, "dry_run": args.dry_run, "monitored": args.monitored}
     if args.query:
@@ -273,15 +297,14 @@ def cmd_runs_create(args) -> int:
     # A real run spends money. Confirm interactively unless told not to — and
     # never silently in a pipe, where nobody is watching.
     if not args.dry_run and not args.yes:
-        if not _tty():
+        if not _interactive():
             err("refusing to start a billable run non-interactively; pass --yes (or --dry-run)")
             return EXIT_USAGE
         print(f"This starts a REAL research run on {prof.origin} — it spends credits "
               f"and takes 15-60 minutes.")
-        # gh #1282: say which Blueprint BEFORE it spends; the 202 is too late.
-        target = (f"Blueprint {args.blueprint}" if getattr(args, "blueprint", None)
-                  else "your active Blueprint (see `deepsieve whoami`; choose with --blueprint)")
-        print(f"It runs on {target}.")
+        # gh #1282: say which Blueprint BEFORE it spends; the 202 is too late. (B1: a billable
+        # run always names one, checked above.)
+        print(f"It runs on Blueprint {args.blueprint}.")
         if input("Continue? [y/N] ").strip().lower() not in ("y", "yes"):
             print("Cancelled.")
             return EXIT_OK
@@ -295,7 +318,8 @@ def cmd_runs_create(args) -> int:
         )
     except ApiError as exc:
         err(str(exc))
-        return EXIT_FAIL
+        # A --query is parsed by a model: the org's model allowance can refuse it (gh #2307).
+        return _api_exit(exc)
 
     if args.json and not args.wait:
         out(created, True)
@@ -351,6 +375,103 @@ def cmd_runs_cancel(args) -> int:
     return EXIT_OK
 
 
+def _last_billed_day(locked_until: str | None) -> str:
+    """`locked_until` is an EXCLUSIVE 00:00Z instant; the last billed UTC day is the day before."""
+    from datetime import datetime, timedelta  # noqa: PLC0415
+
+    try:
+        return (datetime.fromisoformat(str(locked_until)) - timedelta(days=1)).date().isoformat()
+    except ValueError:
+        return str(locked_until)
+
+
+def _yes(prompt: str) -> bool:
+    """A y/N answer; end of input is a no, never a traceback."""
+    try:
+        return input(prompt).strip().lower() in ("y", "yes")
+    except EOFError:
+        return False
+
+
+def cmd_runs_monitoring(args) -> int:
+    """Turn a report's monitoring on or off (gh #2345). A UTC day bills if monitoring was on at
+    any moment of it: OFF stops billing from tomorrow, ON bills today. Both are confirmed like
+    an undo: interactively, or with --yes, never silently in a pipe.
+
+    Turning it back ON after the free 30 days commits 30 UTC days (gh #2359). The API refuses
+    that ON (`lock_confirmation_required`) until it is sent with `commit_lock`: here, a second
+    explicit question, or --commit-lock. --yes alone never commits 30 days. The yes is bound to
+    the date shown (`expected_locked_until`): if a UTC midnight passes before it is sent, the
+    API answers `lock_quote_changed` with the new date and nothing is committed."""
+    rid = _uuid_arg(args.run_id, "run_id")
+    if rid is None:
+        return EXIT_USAGE
+    client, _ = _require_auth(args)
+    if not args.yes:
+        if not _interactive():
+            err("refusing to change monitoring non-interactively; pass --yes")
+            return EXIT_USAGE
+        if args.active:
+            what = "Turn monitoring ON? Past its free 30 days this report bills each UTC day it is on"
+            what += ", and this commits 30 days." if args.commit_lock else "."
+        else:
+            what = "Turn monitoring OFF? It stops being kept fresh, and billing, from tomorrow."
+        if not _yes(f"{what} [y/N] "):
+            print("Cancelled.")
+            return EXIT_OK
+    path = f"/v1/research/runs/{rid}/monitoring"
+    payload: dict = {"active": args.active}
+    if args.active and args.commit_lock:
+        payload["commit_lock"] = True
+        if args.expected_locked_until:
+            payload["expected_locked_until"] = args.expected_locked_until
+    # At most two refusals: the first quote, and one re-quote if a UTC midnight passed while the
+    # person was deciding. A third would be the API contradicting itself; stop rather than loop.
+    for _attempt in range(3):
+        try:
+            body = client.request("PATCH", path, json_body=payload)
+            break
+        except ApiError as exc:
+            if exc.code not in ("lock_confirmation_required", "lock_quote_changed"):
+                err(str(exc))
+                return _api_exit(exc)
+            until = exc.details.get("locked_until")
+            last = _last_billed_day(until)
+            moved = "The UTC day changed, so the date moved. " if exc.code == "lock_quote_changed" else ""
+            ask = (
+                f"{moved}Turning this back on commits 30 days: it stays on, and bills each UTC "
+                f"day, through {last}."
+            )
+            if not _interactive():
+                if args.json:
+                    print(json.dumps({"error": {"code": exc.code, "message": ask, "details": exc.details}}))
+                err(f"{ask} Pass --commit-lock --expected-locked-until {until} to commit to that.")
+                return EXIT_USAGE
+            if not _yes(f"{ask} Commit to 30 days? [y/N] "):
+                print("Cancelled. Monitoring is still off.")
+                return EXIT_OK
+            payload = {"active": True, "commit_lock": True, "expected_locked_until": until}
+    else:
+        err("the API kept refusing the commitment; nothing was changed")
+        return EXIT_FAIL
+    if body.get("active") and body.get("stop_scheduled_at"):
+        human = (
+            f"monitoring stays ON for {rid} through {_last_billed_day(body['stop_scheduled_at'])}, "
+            "the end of the 30 days committed to; it stops after that"
+        )
+    elif body.get("active"):
+        state = "billing daily" if body.get("billing") else (
+            f"free until {body['free_until']}" if body.get("free_until") else "not started yet"
+        )
+        if body.get("locked_until"):
+            state += f", committed through {_last_billed_day(body['locked_until'])}"
+        human = f"monitoring ON for {rid} ({state})"
+    else:
+        human = f"monitoring OFF for {rid}; it stops billing from tomorrow (today still counts)"
+    out(body, args.json, human)
+    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
@@ -426,7 +547,7 @@ def cmd_chat_revert(args) -> int:
 
 
 def cmd_members_list(args) -> int:
-    """Who is in this workspace and how many editor seats are in use (#985).
+    """Who is in this organization and how many editor seats are in use (#985).
     Read-only; inviting is a human-admin action in the UI."""
     client, _ = _require_auth(args)
     try:
@@ -507,7 +628,7 @@ def cmd_changes_undo(args) -> int:
         err("change id must be a UUID (from `deepsieve changes list`)")
         return EXIT_USAGE
     if not args.yes:
-        if not _tty():
+        if not _interactive():
             err("refusing to change data non-interactively; pass --yes")
             return EXIT_USAGE
         if input(f"Undo change {change_id}? This changes your dataset. [y/N] ").strip().lower() not in ("y", "yes"):
@@ -574,25 +695,25 @@ def cmd_holds_list(args) -> int:
 
 
 def _hold_verb(args, verb: str) -> int:
-    """Apply or release one held cell. Both change what the dataset protects, so they are
-    confirmed like an undo: interactively, or with --yes, never silently in a pipe."""
+    """Apply, keep or release one held cell. Each changes what the dataset protects, so they
+    are confirmed like an undo: interactively, or with --yes, never silently in a pipe."""
     client, _ = _require_auth(args)
     if not _CELL_ID.fullmatch(args.cell_id or ""):
         err("cell id must be one `deepsieve holds list` printed (it starts with cel_)")
         return EXIT_USAGE
     body: dict[str, Any] = {}
-    if verb == "apply" and args.finding:
+    if verb in ("apply", "keep") and args.finding:
         try:
             body["finding_evidence_id"] = str(uuid.UUID(args.finding))
         except ValueError:
             err("--finding must be the finding's evidence id (a UUID)")
             return EXIT_USAGE
     if not args.yes:
-        if not _tty():
+        if not _interactive():
             err("refusing to change data non-interactively; pass --yes")
             return EXIT_USAGE
-        what = "Take research's newer value for" if verb == "apply" else "Stop protecting"
-        if input(f"{what} this cell? [y/N] ").strip().lower() not in ("y", "yes"):
+        what = _HOLD_ASK[verb]
+        if input(f"{what}? [y/N] ").strip().lower() not in ("y", "yes"):
             print("Cancelled.")
             return EXIT_OK
     headers = {"Idempotency-Key": args.idempotency_key} if args.idempotency_key else None
@@ -603,15 +724,30 @@ def _hold_verb(args, verb: str) -> int:
     except ApiError as exc:
         err(str(exc))
         return EXIT_FAIL
-    done = "applied; the cell stays protected" if verb == "apply" else "released; research may update it"
-    out(result, args.json, f"{done}: {result.get('column')} = {result.get('value')!r}")
+    out(result, args.json, f"{_HOLD_DONE[verb]}: {result.get('column')} = {result.get('value')!r}")
     return EXIT_OK
 
 
+_HOLD_ASK = {
+    "apply": "Take research's newer value for this cell",
+    "keep": "Keep your value and dismiss research's newer value for this cell",
+    "release": "Stop protecting this cell",
+}
+_HOLD_DONE = {
+    "apply": "applied; the cell stays protected",
+    "keep": "kept; research's value is dismissed and the cell stays protected",
+    "release": "released; research may update it",
+}
+
+
 def cmd_holds_apply(args) -> int:
     return _hold_verb(args, "apply")
 
 
+def cmd_holds_keep(args) -> int:
+    return _hold_verb(args, "keep")
+
+
 def cmd_holds_release(args) -> int:
     return _hold_verb(args, "release")
 
@@ -651,6 +787,10 @@ def _print_merge(body: dict) -> None:
               "or pass --accept-survivor-on-ties")
 
 
+#: Merge refusals fixed by changing the command, not by retrying: exit 2, not 1.
+_MERGE_USAGE_CODES = frozenset({"ties_unresolved", "merge_across_parents"})
+
+
 def cmd_merge_preview(args) -> int:
     """What a merge would do; writes nothing (#1577 2c-3)."""
     client, _ = _require_auth(args)
@@ -661,7 +801,7 @@ def cmd_merge_preview(args) -> int:
         out_ = client.request("POST", "/v1/merges/preview", json_body=body)
     except ApiError as exc:
         err(str(exc))
-        return EXIT_FAIL
+        return EXIT_USAGE if exc.code in _MERGE_USAGE_CODES else EXIT_FAIL
     if args.json:
         out(out_, True)
     else:
@@ -678,7 +818,7 @@ def cmd_merge_apply(args) -> int:
         return EXIT_USAGE
     body["accept_survivor_on_ties"] = bool(args.accept_survivor_on_ties)
     if not args.yes:
-        if not _tty():
+        if not _interactive():
             err("refusing to change data non-interactively; pass --yes")
             return EXIT_USAGE
         prompt = f"Merge {len(body['loser_ids'])} row(s) into {args.survivor}? This changes your dataset. [y/N] "
@@ -692,8 +832,9 @@ def cmd_merge_apply(args) -> int:
         err(str(exc))
         # 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.
-        return EXIT_USAGE if exc.code == "ties_unresolved" else EXIT_FAIL
+        # apart from a failure without --json. So is a merge across parents (#2254): no retry
+        # can succeed, only a different set of rows.
+        return EXIT_USAGE if exc.code in _MERGE_USAGE_CODES else EXIT_FAIL
     if args.json:
         out(out_, True)
     else:
@@ -1005,8 +1146,8 @@ 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("--blueprint", help="Blueprint id to research (default: your active one, "
-                    "which `deepsieve whoami` shows)")
+    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"])
     rc.add_argument("--dry-run", action="store_true", help="free simulated run (~15s)")
     rc.add_argument("--no-monitor", dest="monitored", action="store_false",
@@ -1028,6 +1169,28 @@ def build_parser() -> argparse.ArgumentParser:
     rx.add_argument("run_id")
     rx.set_defaults(func=cmd_runs_cancel)
 
+    rm = runs.add_parser(
+        "monitoring",
+        help="turn a report's monitoring on or off (ON bills daily past the free 30 days)",
+        parents=[common],
+    )
+    rm.add_argument("run_id")
+    onoff = rm.add_mutually_exclusive_group(required=True)
+    onoff.add_argument("--on", dest="active", action="store_true")
+    onoff.add_argument("--off", dest="active", action="store_false")
+    rm.add_argument("--yes", action="store_true", help="do not ask for confirmation")
+    rm.add_argument(
+        "--commit-lock",
+        action="store_true",
+        help="with --on after the free 30 days: commit to 30 days of monitoring (billed daily)",
+    )
+    rm.add_argument(
+        "--expected-locked-until",
+        default="",
+        help="with --commit-lock: the locked_until you were quoted; refused if the date has moved",
+    )
+    rm.set_defaults(func=cmd_runs_monitoring)
+
     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")
@@ -1041,8 +1204,8 @@ def build_parser() -> argparse.ArgumentParser:
         cp.add_argument("action_id")
         cp.set_defaults(func=fn)
 
-    members = sub.add_parser("members", help="your workspace's team", parents=[common]).add_subparsers(dest="sub", required=True)
-    ml = members.add_parser("list", help="who is in the workspace, and seat usage", parents=[common])
+    members = sub.add_parser("members", help="your organization's team", parents=[common]).add_subparsers(dest="sub", required=True)
+    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)
@@ -1077,6 +1240,12 @@ def build_parser() -> argparse.ArgumentParser:
     ha.add_argument("--yes", action="store_true", help="do not ask for confirmation")
     ha.add_argument("--idempotency-key", help="make a retry safe")
     ha.set_defaults(func=cmd_holds_apply)
+    hk = holds.add_parser("keep", help="keep your value and dismiss research's newer one (needs data:write)", parents=[common])
+    hk.add_argument("cell_id")
+    hk.add_argument("--finding", help="the `finding` id `holds list` printed for the value you reviewed (a newer one since is refused)")
+    hk.add_argument("--yes", action="store_true", help="do not ask for confirmation")
+    hk.add_argument("--idempotency-key", help="make a retry safe")
+    hk.set_defaults(func=cmd_holds_keep)
     hr = holds.add_parser("release", help="stop protecting a cell (needs data:write)", parents=[common])
     hr.add_argument("cell_id")
     hr.add_argument("--yes", action="store_true", help="do not ask for confirmation")
@@ -1143,7 +1312,7 @@ def main(argv: list[str] | None = None) -> int:
         return EXIT_FAIL
     except ApiError as exc:
         err(str(exc))
-        return EXIT_FAIL
+        return _api_exit(exc)
 
 
 if __name__ == "__main__":  # pragma: no cover

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

@@ -208,7 +208,7 @@ def test_commands_refuse_without_a_credential(capsys):
 def test_billable_run_is_refused_non_interactively_without_yes(monkeypatch, capsys):
     cfg.save_profile(cfg.Profile(name="default", origin="https://x.test", api_key="k"))
     monkeypatch.setattr("deepsieve_cli.main._tty", lambda: False)
-    code = main(["runs", "create", "--query", "anything"])
+    code = main(["runs", "create", "--query", "anything", "--blueprint", "bp-a"])
     assert code == 2
     assert "refusing to start a billable run" in capsys.readouterr().err
 
@@ -976,6 +976,19 @@ def test_an_unsettled_tie_surfaces_the_servers_refusal(monkeypatch, capsys):
     assert f"author::{_L}" in capsys.readouterr().err
 
 
+def test_a_merge_across_parents_exits_as_a_usage_error(monkeypatch, capsys):
+    """#2254: no retry can succeed, only different rows, so a script sees 2, never 1."""
+    _signed_in(monkeypatch)
+    body = {"error": {"type": "conflict_error", "code": "merge_across_parents", "retriable": False,
+                      "message": "These books belong to different publishers (A, B).",
+                      "param": "loser_ids"}}
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: httpx.Response(409, json=body)))
+    for argv in (["merge", "apply", "books", "--survivor", _S, "--loser", _L, "--yes"],
+                 ["merge", "preview", "books", "--survivor", _S, "--loser", _L]):
+        assert main(argv) == 2, argv
+        assert "different publishers" in capsys.readouterr().err
+
+
 # ---------------------------------------------------------------------------
 # #2196 PR 2: holds list | apply | release
 # ---------------------------------------------------------------------------
@@ -1045,6 +1058,31 @@ def test_holds_apply_posts_the_finding_and_the_idempotency_key(monkeypatch, caps
     assert "stays protected" in capsys.readouterr().out
 
 
+def test_holds_keep_posts_the_finding_to_keep_and_asks_in_a_pipe(monkeypatch, capsys):
+    """#2294: Keep mine, the third verb, confirmed like the other two."""
+    _signed_in(monkeypatch)
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["path"], seen["key"] = request.url.path, request.headers.get("idempotency-key")
+        seen["body"] = json.loads(request.content or b"{}")
+        return httpx.Response(200, json={"object": "cell", "column": "author", "value": "Austen",
+                                         "held": True})
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    rc = main(["holds", "keep", CELL, "--finding", CID, "--yes", "--idempotency-key", "k-3"])
+    assert rc == 0
+    assert (seen["path"], seen["key"]) == (f"/v1/cells/{CELL}/keep", "k-3")
+    assert seen["body"] == {"finding_evidence_id": CID}
+    assert "dismissed" in capsys.readouterr().out
+
+    monkeypatch.setattr("deepsieve_cli.main._tty", lambda: False)
+    seen.clear()
+    assert main(["holds", "keep", CELL]) == 2
+    assert "pass --yes" in capsys.readouterr().err
+    assert seen == {}, "nothing sent"
+
+
 def test_holds_release_refuses_a_malformed_cell_id_and_sends_nothing(monkeypatch, capsys):
     """The id goes into the URL path, so a crafted one could reach another endpoint."""
     _signed_in(monkeypatch)
@@ -1052,3 +1090,271 @@ def test_holds_release_refuses_a_malformed_cell_id_and_sends_nothing(monkeypatch
     monkeypatch.setattr(httpx, "Client", _mock(lambda r: calls.append(r) or httpx.Response(200)))
     assert main(["holds", "release", "../research/runs/x/cancel#", "--yes"]) == 2
     assert calls == []
+
+
+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)."""
+    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] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        sent.append(f"{request.method} {request.url.path}")
+        return httpx.Response(202, json={"id": "run_1", "status": "queued"})
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    code = main(["runs", "create", "--query", "anything", "--yes"])
+    err = capsys.readouterr().err
+    assert code == 2, err
+    assert "--blueprint" in err and "whoami" in err
+    assert sent == [], sent
+    # Positive control: the same handler DOES see a request when the call is allowed.
+    assert main(["runs", "create", "--query", "anything", "--dry-run"]) == 0
+    assert sent == ["POST /v1/research/runs"], sent
+
+
+def test_a_run_refused_by_the_model_allowance_exits_5_not_1(monkeypatch, capsys):
+    """gh #2307: a script can tell "the org's model allowance is used" from a failure."""
+    _signed_in(monkeypatch)
+    body = {"error": {"type": "rate_limit_error", "code": "model_allowance_exhausted",
+                      "retriable": False, "param": None,
+                      "message": "Your organization has used this period's allowance."}}
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: httpx.Response(429, json=body)))
+    assert main(["runs", "create", "--query", "EU payment vendors", "--blueprint", "bp-a", "--yes"]) == 5
+    assert "allowance" in capsys.readouterr().err
+
+
+# ── runs monitoring (gh #2345) ───────────────────────────────────────────────
+
+RUN = "3f2a8e1c-0000-4000-8000-000000002345"
+
+
+def _monitoring_body(active: bool) -> dict:
+    return {
+        "object": "monitoring",
+        "run_id": RUN,
+        "active": active,
+        "units": 2,
+        "in_free_window": True,
+        "free_until": "2026-10-28",
+        "billing": False,
+        "reruns": {"status": "ok"},
+    }
+
+
+@pytest.mark.parametrize("flag,active", [("--on", True), ("--off", False)])
+def test_runs_monitoring_patches_the_state_asked_for(monkeypatch, capsys, flag, active):
+    _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)
+        return httpx.Response(200, json=_monitoring_body(active))
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "monitoring", RUN, flag, "--yes"]) == 0
+    assert seen == {
+        "method": "PATCH",
+        "path": f"/v1/research/runs/{RUN}/monitoring",
+        "body": {"active": active},
+    }
+    text = capsys.readouterr().out
+    assert ("ON" if active else "OFF") in text
+
+
+def test_runs_monitoring_is_refused_in_a_pipe_without_yes_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", "monitoring", RUN, "--on"]) == 2
+    assert "pass --yes" in capsys.readouterr().err
+    assert calls == []
+
+
+def test_runs_monitoring_needs_on_or_off_and_a_uuid(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr(httpx, "Client", _mock(lambda r: pytest.fail("no request expected")))
+    with pytest.raises(SystemExit) as exc:
+        main(["runs", "monitoring", RUN, "--yes"])  # neither --on nor --off
+    assert exc.value.code == 2
+    assert main(["runs", "monitoring", "../billing", "--off", "--yes"]) == 2
+
+
+def test_runs_monitoring_surfaces_a_404(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            404,
+            json={"error": {"code": "not_found", "message": "This run has no monitoring to set"}},
+        )
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "monitoring", RUN, "--off", "--yes"]) == 1
+    assert "no monitoring" in capsys.readouterr().err
+
+
+# ── runs monitoring: the 30-day re-enable lock (gh #2345 x #2359) ────────────
+
+_LOCK_409 = {
+    "error": {
+        "code": "lock_confirmation_required",
+        "message": "Turning this back on commits 30 days",
+        "param": "commit_lock",
+        "retriable": False,
+        "details": {"locked_until": "2026-10-28T00:00:00+00:00"},
+    }
+}
+
+
+def _lock_handler(seen: list):
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content)
+        seen.append(body)
+        if not body.get("commit_lock"):
+            return httpx.Response(409, json=_LOCK_409)
+        return httpx.Response(
+            200,
+            json={**_monitoring_body(True), "locked_until": "2026-10-28T00:00:00+00:00"},
+        )
+
+    return handler
+
+
+def test_a_lock_in_a_pipe_is_refused_naming_the_last_day_and_the_flag(monkeypatch, capsys):
+    """--yes alone never commits 30 days: a script must say --commit-lock."""
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._tty", lambda: False)
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_lock_handler(seen)))
+    assert main(["runs", "monitoring", RUN, "--on", "--yes"]) == 2
+    err_text = capsys.readouterr().err
+    print("refusal:", err_text)
+    assert "through 2026-10-27" in err_text and "--commit-lock" in err_text
+    assert "--expected-locked-until 2026-10-28T00:00:00+00:00" in err_text
+    assert seen == [{"active": True}]
+
+
+def test_commit_lock_commits_in_one_call(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_lock_handler(seen)))
+    assert main(["runs", "monitoring", RUN, "--on", "--yes", "--commit-lock"]) == 0
+    assert seen == [{"active": True, "commit_lock": True}]
+    assert "committed through 2026-10-27" in capsys.readouterr().out
+
+
+def test_interactively_the_lock_is_a_second_explicit_question(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    answers = iter(["y", "y"])
+    monkeypatch.setattr("builtins.input", lambda prompt="": next(answers))
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_lock_handler(seen)))
+    assert main(["runs", "monitoring", RUN, "--on"]) == 0
+    # The yes is bound to the date the person was shown (gh #2345).
+    assert seen == [
+        {"active": True},
+        {
+            "active": True,
+            "commit_lock": True,
+            "expected_locked_until": "2026-10-28T00:00:00+00:00",
+        },
+    ]
+
+
+def test_declining_the_lock_sends_nothing_more(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    answers = iter(["y", "n"])
+    monkeypatch.setattr("builtins.input", lambda prompt="": next(answers))
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_lock_handler(seen)))
+    assert main(["runs", "monitoring", RUN, "--on"]) == 0
+    assert seen == [{"active": True}]
+    assert "still off" in capsys.readouterr().out
+
+
+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."""
+    import io
+
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("sys.stdout.isatty", lambda: True, raising=False)
+    monkeypatch.setattr("deepsieve_cli.main._tty", lambda: True)
+    monkeypatch.setattr("sys.stdin", io.StringIO("y\ny\ny\n"))
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_lock_handler(seen)))
+    rc = main(["runs", "monitoring", RUN, "--on"])
+    print("piped yes:", rc, seen)
+    assert rc == 2
+    assert seen == [], "no request at all: a pipe is refused before the first question"
+
+
+def test_a_lock_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(_lock_handler(seen)))
+    assert main(["runs", "monitoring", RUN, "--on", "--yes", "--json"]) == 2
+    out_json = json.loads(capsys.readouterr().out)
+    assert out_json["error"]["code"] == "lock_confirmation_required"
+    assert out_json["error"]["details"] == {"locked_until": "2026-10-28T00:00:00+00:00"}
+
+
+def test_a_moved_date_is_asked_again_with_the_new_date(monkeypatch, capsys):
+    """Quoted before 00:00Z, confirmed after: the API answers `lock_quote_changed` with the new
+    date; the person is asked again and the new yes is bound to the new date."""
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    answers = iter(["y", "y", "y"])
+    prompts: list = []
+    monkeypatch.setattr("builtins.input", lambda prompt="": prompts.append(prompt) or next(answers))
+    seen: list = []
+    moved = {
+        "error": {
+            "code": "lock_quote_changed",
+            "message": "The UTC day changed",
+            "details": {"locked_until": "2026-10-29T00:00:00+00:00"},
+        }
+    }
+
+    def handler(request):
+        body = json.loads(request.content)
+        seen.append(body)
+        if not body.get("commit_lock"):
+            return httpx.Response(409, json=_LOCK_409)
+        if body.get("expected_locked_until") != "2026-10-29T00:00:00+00:00":
+            return httpx.Response(409, json=moved)
+        return httpx.Response(200, json={**_monitoring_body(True), "locked_until": "2026-10-29T00:00:00+00:00"})
+
+    monkeypatch.setattr(httpx, "Client", _mock(handler))
+    assert main(["runs", "monitoring", RUN, "--on"]) == 0
+    assert [b.get("expected_locked_until") for b in seen] == [
+        None,
+        "2026-10-28T00:00:00+00:00",
+        "2026-10-29T00:00:00+00:00",
+    ]
+    assert "through 2026-10-28" in prompts[-1] and "date moved" in prompts[-1]
+
+
+def test_end_of_input_at_the_lock_question_is_a_no_not_a_traceback(monkeypatch, capsys):
+    _signed_in(monkeypatch)
+    monkeypatch.setattr("deepsieve_cli.main._interactive", lambda: True)
+    answers = iter(["y"])
+
+    def _input(prompt=""):
+        try:
+            return next(answers)
+        except StopIteration:
+            raise EOFError from None
+
+    monkeypatch.setattr("builtins.input", _input)
+    seen: list = []
+    monkeypatch.setattr(httpx, "Client", _mock(_lock_handler(seen)))
+    assert main(["runs", "monitoring", RUN, "--on"]) == 0
+    assert seen == [{"active": True}]