Render hunt-page ruleset tracking and hunt provenance fields

AGENTS.md

@@ -98,6 +98,7 @@ Details in [`specs/04-testing.md`](./specs/04-testing.md). The shape:
 - Conventional commit prefixes (`feat:`, `fix:`, `refactor:`, `chore:`, `docs:`, `test:`).
 - Small, scoped commits — each one should be independently reviewable.
 - **Don't reference ticket IDs or internal project codes in commit messages, PR titles, or PR descriptions.** This repo is public; published artefacts shouldn't leak internal references. Track tickets in the internal tracker, not the git history.
+- **Branch names are the exception, and the merge is where they're contained.** A change spanning this repo and the SDK must use the *identical* branch name in both, because CI resolves the companion SDK by `$CI_COMMIT_BRANCH` (`.gitlab-ci.yml`) — so a shared ticket-prefixed name is often the coordinating key and is deliberately allowed. It does reach public history, but only through the **default merge subject** (`Merge pull request #N from org/TICKET-…`). **Squash-merge with an explicit clean subject**, and it never lands. Prefer a shared descriptive name over a ticket prefix when one reads just as well.
 - **Don't name private companion repos in PR descriptions or commit messages on this repo.** Refer to internal services by category, not by repo name.
 - No AI-attribution trailers on commits (`Co-Authored-By: Claude …`, "Generated with Claude Code", etc.) — they're noise and they don't belong in project history.
 - PRs that depend on an unreleased `polyswarm-api` surface must link the SDK PR under a `## Requires` section (see `specs/05-sdk-contract.md`).

pyproject.toml

@@ -22,7 +22,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "polyswarm_api>=4.3.0,<5.0.0",
+    "polyswarm_api>=4.4.0,<5.0.0",
     "click>=7.1",
     "colorama>=0.4.6",
     "click-log>=0.4.0",

specs/01-architecture.md

@@ -38,6 +38,14 @@ The console-script entry (`__main__.py`) calls `polyswarm_cli(prog_name='polyswa
 
 The transport-error branch matches by **ancestry class name** — it intersects `{c.__name__ for c in type(e).__mro__}` with `{'HTTPError', 'RequestException', 'ConnectionError', 'SSLError'}` — because those classes come from the SDK's HTTP dependency (`httpx`; `requests` historically) and shouldn't be imported here directly. `httpx` roots every request/transport/status error at `HTTPError`, so ancestry matching covers all its leaf classes (`ConnectError`, `ReadTimeout`, `RemoteProtocolError`, `ProxyError`, …) without enumerating them.
 
+**The order of the `except` clauses is load-bearing, not stylistic.** The SDK has its own
+`api_exceptions.RequestException`, which subclasses `PolyswarmException` but shares the bare
+name `requests` used — so it satisfies the ancestry-name test above and would take the
+transport branch (exit `1`, "contact support") if it ever reached it. It exits `2` only
+because the `PolyswarmException` clause is matched **before** the transport branch. Reordering
+those clauses silently changes the exit code of every SDK request refusal, `FAVORITE_LIMIT`
+included; `ExitCodeHierarchyTest` pins the subclass relation the ordering rests on.
+
 ## The SDK wrapper — `polyswarm.py`
 
 `class Polyswarm(PolyswarmAPI)` subclasses the SDK's sync client to add **CLI-only** behaviour the SDK has no reason to ship:
@@ -74,7 +82,8 @@ The catalogue of groups and the SDK methods each wraps is in [`02-commands.md`](
 
 ## Support — `utils.py`, `exceptions.py`
 
-- **`utils.py`** — `parallelize`/`parallel_executor` (thread-pool fan-out with per-item exception aggregation: collects results, logs per-item no-results, raises an aggregate `NoResultsException`/`NotFoundException`/`InternalFailureException` at the end), `parallel_executor_iterable_results` (the same, for SDK methods that return generators — it materialises each generator inside the worker so per-item exception handling still fires), and input parsing/validation (`parse_hashes`, hash/IP detection).
+- **`utils.py`** — `parallelize`/`parallel_executor` (thread-pool fan-out with per-item exception aggregation: collects results, logs per-item no-results, raises an aggregate `NoResultsException`/`NotFoundException`/`InternalFailureException` at the end) and `parallel_executor_iterable_results` (the same, for SDK methods that return generators — it materialises each generator inside the worker so per-item exception handling still fires), plus `collect_files` and the detection helpers (`is_valid_id`, `is_ip`, `is_domain`, `is_url`).
+- **`client/utils.py`** — `parse_hashes` and the click parameter validators (`validate_id`, `validate_hash(es)`, `validate_key`, …). Note the module is `client/utils.py`, not the top-level `utils.py` above — the two are distinct and easily confused.
 - **`exceptions.py`** — the CLI's own hierarchy, **distinct from the SDK's**: `PolyswarmException` → `NoResultsException`, `NotFoundException`, `InternalFailureException`, `PartialResultsException`. `ExceptionHandlingGroup` catches both these and the SDK's `api_exceptions.*`.
 
 ## Lifecycle of a command (end to end)

specs/02-commands.md

@@ -25,19 +25,43 @@ The top-level command groups, what each is for, and the primary `polyswarm-api`
 | `report` (`report.py`) | Create/fetch/download reports; `prompt-config` subgroup; LLM reports | `report_create`, `report_wait_for`, `report_download`, `report_get`, `llm_report_{create,get,download}`, `prompt_config_{create,get,update,list}` |
 | `report-template` (`report_template.py`) | Manage report templates + logos | `report_template_{create,update,get,list}`, `report_template_logo_{download,upload}` |
 | `engine` → `votes` / `assertions` (`engine.py`) | Consolidated votes/assertions bundles per engine | `votes_{create,get,delete,list}`, `assertions_{create,get,delete,list}` |
-| `live` (`live.py`) | Live YARA hunts: start/stop, feed, results | `live_start`, `live_stop`, `live_feed`, `live_result`, `live_feed_delete` |
+| `live` (`live.py`) | Live YARA hunts: start/stop, feed, results. `feed` takes `--since` in **SECONDS** (default 86400 — 24h; `0` means no time filter at all, and a negative is refused at parse time rather than forwarded). **`0` is the API's contract, not a CLI convention:** the endpoint applies the window only when `since` is truthy, so `0` and an absent parameter behave identically. The CLI's own test can only pin that it forwards `0` rather than dropping it — which is the half that can regress here, plus `--livescan-id` (the drill-down for the per-ruleset new-results badge `rules list` renders — the detail view deliberately does not carry the badge; the badge counts the hunt across **every** community it runs in, public and private, while the feed shows one at a time, so a multi-community hunt lists fewer rows than the badge reports) and `--max-results` (stop after N; unset means every page, as before). Both are guaranteed by the pin (see [05-sdk-contract.md](./05-sdk-contract.md) §Current floor) and called directly; they are forwarded only when passed purely so a pre-existing invocation's call shape is unchanged — the request is identical either way | `live_start`, `live_stop`, `live_feed`, `live_result`, `live_feed_delete` |
 | `historical` (`historical.py`) | Historical hunts: CRUD + results | `historical_{get,create,update,list}`, `historical_delete_multiple`, `historical_delete_list`, `historical_results_multiple`, `historical_result`, `historical_results_delete` |
 | `tag` (`tags.py`) | Tag CRUD | `tag_{create,delete,get,list}` |
 | `link` (`links.py`) | Tag/family links on artifacts | `tag_link_multiple`, `tag_link_get`, `tag_link_list` |
 | `family` (`families.py`) | Malware-family CRUD | `family_{create,update,delete,get,list}` |
-| `rules` (`rules.py`) | YARA ruleset CRUD | `ruleset_{create,delete,update,get,list}` |
+| `rules` (`rules.py`) | YARA ruleset CRUD plus `favorite <id> [--unfavorite]` (the star toggle: renders the new state + the server-owned "N of M used" budget, and converts the machine-readable `FAVORITE_LIMIT` refusal into a clean actionable message at exit 2, never 1 — 1 is reserved for no-results/not-found; 2 is the broad bucket `ExceptionHandlingGroup` maps the PolyswarmException hierarchies to. **2 does not identify a server refusal:** click exits 2 for a `UsageError` too, so a scripted caller cannot tell “the favorite budget is full” from “you passed a bad flag” without reading the message). `list` takes the server-side filters `--name` / `--status active` / `--favorites-only` / `--has-new-results` (conjunctive; the list is keyset-paginated, so filtering locally would mean walking every page). `rules favorite` and the `rules list` filters need SDK 4.4.0, which the pin requires (see [05-sdk-contract.md](./05-sdk-contract.md) §Current floor), so they are called directly. The formatters read the hunt-page fields directly: the pin guarantees the SDK parses them, so `None` means the *server* had no answer | `ruleset_{create,delete,update,get,list,favorite}` |
 | `metadata` (`metadata.py`) | Rerun metadata; scan lookup; IP/URL analysis | `rerun_metadata`, `scan_lookup`, `submit_url` |
 | `activity` (`event.py`) | List account activity/events | `event_list` |
 | `account` (`account.py`) | Account whois / features | `account_whois`, `account_features` |
 | `notification` / webhooks (`notification.py`, `notification_webhook.py`) | Notification webhook CRUD | `notification_webhook_{create,get,update,delete,list}` |
 | `bundle` (`bundle.py`) | Sample bundle tasks | `sample_bundle_task_create`, `sample_bundle_task_get`, `sample_bundle_download` |
 | `sample` (`sample.py`) | Fetch a consolidated sample view | `sample` |
 
+> **`live feed --since` defaults to 86400 seconds (24h), not 1440.** The old
+> default was written as `24 * 60` against an SDK docstring that said the
+> parameter was minutes; the server has always read **seconds**, so the real
+> default window was 24 minutes while the ruleset badge beside it counts 24
+> hours. The fix is here rather than on the wire: the endpoint takes ~197k
+> requests per 30 days carrying `since` from clients outside our control, and
+> re-basing the server to minutes would widen every one of them 60x with no
+> error. `historical list --since` is seconds too — those two agree.
+>
+> **Migration, for a caller who relied on the old behaviour:** pass
+> `--since 1440` to get the 24-minute window back. Two effects compound and
+> the second is the sharper one — the default window widens ~60x, and
+> `--max-results` is unset by default, so a bare `live feed` pages through all
+> of it rather than stopping. This repo has no CHANGELOG, so the note lives
+> here and in the command's own `--help` rather than only in a release-time
+> reminder.
+>
+> **A third `--since` is genuinely MINUTES and must stay that way:**
+> `download stream --since` (`client/download.py`, `IntRange(1, 2880)`,
+> default `1440`) hits a different endpoint that really does read minutes. That
+> `1440` is the same literal `live feed` is being corrected away from, and is the
+> likeliest origin of the original mistake — check which endpoint you are on
+> before copying a default between them.
+
 ## Adding to the catalogue
 
 When you add or materially change a group, update its row (and add per-subcommand detail here if the behaviour is non-obvious). The `AGENTS.md` §"When adding a new command family" checklist covers the wiring + formatter + test steps.

specs/03-formatters.md

@@ -14,7 +14,7 @@ How command output is rendered: the `BaseOutput` interface, the concrete formatt
 
 ## The interface — `base.py`
 
-`BaseOutput(output, **kwargs)` holds the output stream and exposes a method per resource type, each raising `NotImplementedError`. The set includes (non-exhaustive): `artifact_instance`, `historical_result`, `hunt`, `hunt_deletion`, `local_artifact`, `ruleset`, `ioc`, `iocs`, `known_host`, `metadata`, `artifact_metadata`, `tag_link`, `family`, `tag`, `known_good`, `sandbox_list`, `sandbox_task`, `sandbox_tasks`, `bundle_task`, `sample`. Concrete formatters add further methods as command families grow (e.g. `report_task`, `webhook`, `llm_prompt_config`, `metadata_field_properties`); keep `text` and `json` in sync.
+`BaseOutput(output, **kwargs)` holds the output stream and exposes a method per resource type, each raising `NotImplementedError`. The set includes (non-exhaustive): `artifact_instance`, `historical_result`, `hunt`, `hunt_deletion`, `local_artifact`, `ruleset`, `ruleset_favorite`, `ioc`, `iocs`, `known_host`, `metadata`, `artifact_metadata`, `tag_link`, `family`, `tag`, `known_good`, `sandbox_list`, `sandbox_task`, `sandbox_tasks`, `bundle_task`, `sample`. Concrete formatters add further methods as command families grow (e.g. `report_task`, `webhook`, `llm_prompt_config`, `metadata_field_properties`); keep `text` and `json` in sync.
 
 ## Concrete formatters
 
@@ -142,7 +142,34 @@ either field) never raises `AttributeError`; an SDK without `.state` simply neve
 the known-good branch, which is the safe fallback — the pre-known-good rendering. That
 degradation is belt-and-braces, not a supported configuration: `.state` is load-bearing
 here with no substitute. Both attributes ship in SDK **4.1.0**, but the dependency floor is
-`polyswarm_api>=4.2.0` — set by two *other* behaviours the CLI depends on, both of which
+the value in `pyproject.toml` — see [05-sdk-contract.md](./05-sdk-contract.md)
+§Current floor, which is authoritative, since repeating the number here is what let this
+line go stale before. Its *rationale* is two behaviours that landed in 4.2.0 and still hold
+transitively; those two
 fail silently on 4.1.0 (see [`05-sdk-contract.md`](./05-sdk-contract.md) §Version pin) — so
 every supported install has them. `JSONOutput` needs no change — it dumps the resource's
 `.json`, which already carries the raw `state` and `known_good` keys.
+
+## Hunt-page tracking fields (rulesets + historical hunts)
+
+Rendering rules that are deliberate, not incidental. Every one of these fields is
+parsed by the pinned SDK, so the attribute always exists and `None` means the
+**server** had no answer — never an older SDK (the floor forbids one; see
+[`05-sdk-contract.md`](./05-sdk-contract.md) §Current floor). The formatters read
+the attributes directly:
+
+- `rule_count` / `historical_hunt_count`: `0` renders as a real zero;
+  `None` (the server had no answer) omits the line — never shown as 0.
+- `favorite` is truthy-only ("Favorite: yes"): False and None both print
+  nothing, deliberately indistinguishable.
+- `new_results_count` is the server's STORED badge (refreshed by its
+  scheduled job; the window is the server's and the response does not carry
+  it, so the label deliberately does not name one): a number renders with its
+  `new_results_counted_at` staleness marker beside it; `None` (never
+  refreshed / no live hunt) omits both lines.
+- `ruleset_favorite` renders the toggle response: `Favorite: yes/no`, the
+  `favorited_at` timestamp when starred, and the server-owned budget as
+  "Favorites used: N of M" — the client never counts.
+- `source_rule_changed` is tri-state: `None` means UNKNOWN, not "unchanged",
+  and prints nothing; the label names its reference point — "changed since
+  this hunt froze it" — so it cannot read as "edited recently".