scan: fetch the unscanned backlog, not the newest ten posts again

[arch-colony]

Reported 2026-08-17: make run appeared to do nothing.

It fetched the ten newest posts, recognised all ten from local memory, skipped them, and exited reporting success — because the Sentinel keeps up with the front page, so the newest ten are exactly the ten it has already moderated. --limit 10 meant "ten posts, probably none of which need moderating".

The filtering was in the wrong place. Asking the server for unscanned posts and filtering locally by remembered ids look equivalent and are not: one returns work, the other returns the front page and then throws it away.

Measured against production just now:

GET /posts?limit=1&sort=new                          total = 15,638
GET /posts?limit=1&sort=new&sentinel_scanned=false   total = 12,877   <- the backlog
GET /posts?limit=1&sort=new&sentinel_scanned=true    total =  2,761

12,877 + 2,761 = 15,638. The filter partitions the corpus exactly, and the backlog is 12,877 posts deep.

What changed

Scan mode now sends ?sentinel_scanned=false by default. --force continues to mean "revisit finished work" and sends no filter; new --include-scanned asks for the same without also discarding local memory.

The policy is a named function rather than an inline conditional because it is a decision worth testing directly: scanned_filter_for(args) returns False / None, and None must never be sent as a filter value.

Why this was blocked until today

It needs sentinel_scanned= on iter_posts(), which shipped in colony-sdk 1.34.0 — published to PyPI today. Hence the >=1.34.0,<2 floor in requirements: an older SDK raises TypeError on the keyword rather than silently ignoring it, which is the right way round. A silently-ignored keyword would have reproduced the original bug with no signal, which is the same failure shape as the API dropping an undeclared query param.

Verification

Installed from a clean venv against the published 1.34.0 (not a local build) and captured what actually goes on the wire:

sentinel_scanned=False  ->  /posts?sort=new&limit=20&sentinel_scanned=false
sentinel_scanned=None   ->  /posts?sort=new&limit=20
sentinel_scanned=True   ->  /posts?sort=new&limit=20&sentinel_scanned=true

201 tests pass, ruff clean. Mutation-verified: reverting scanned_filter_for to the old always-None behaviour kills 4 tests; leaving the helper correct while the fetch ignores it kills 1.

Caveat worth knowing when you run it

Marking while iterating shifts the result set. iter_posts paginates by offset, so a post you mark leaves the sentinel_scanned=False set and everything behind it slides forward — the next page skips as many posts as you marked. Collect the run before marking, or re-request from offset 0 each pass. A single page (--limit <= page size) is unaffected, which is the usual moderation-pass shape.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pxqw6ZyFv5f4rt5HFwtafs