Tracking: split run_scan into discover, select, one mode dispatch and render phases #843

[agent] Filed by the scheduled architecture audit routine (CLI and core). Register: C11.

Kind: tracking. Source: review §2.2, §2.6 and R5; register C11.

Problem

run_scan is one 1,540-line function on 045d7ec (the review measured 1,499 at 2463257). It does everything a scan does, in order:

• mode folding, socket.yml policy loading, the PATH fan-out, path-scope parsing, the rollout cap and the offline refusal (L1429–L1521);``
• the crawl, the lockfile supplement, the vendored-ledger supplement and the package/path filters (L1560–L1771);``
• a "no packages" exit with its own JSON and human arms (L1772–L1893);``
• the concurrent batch query with the proxy fallback, the fold and the patch counts (L1932–L2132);``
• a JSON arm and a human arm that each dispatch all three modes again.

The JSON arm is L2141–L2428 and the human arm follows it:

The mode is still three booleans (apply/vendor/hosted, L1525–L1527),`` derived from args.mode and branched on in about 27 conditions. Output mode leaks into the engine: `discover_selected` takes progress, warning and `json_warnings: Option<&mut Value>` parameters, so the selection step can't be shared between the two arms.

Impact

Every scan behavior change has to be made twice, once per output arm, and every mode-specific fix touches the same 1,540-line body. The open arch-audit issues on scan's proxy fallback, batch chunking and the JSON error shape (#647, #675, #704) all edit this function. Its size also forces the Box::pin/boxed_* indirections that keep the debug-build poll frame under Windows' 1 MiB main-thread stack.

Target design

run_scan becomes a short pipeline over typed phase results, with rendering only at the end:

1. prepare (policy, scope, cap, offline) → ScanSetup;
2. collect_inventory (crawl, supplements, filters) → ScanInventory;
3. query_patches (batches, fallback, fold, counts) → PatchQuery;
4. select (rows, partitions, rollout plan, computed once) → Selection;
5. one match mode that hands Selection to the hosted, agent or vendored consumer, which returns a typed outcome;
6. render_json or render_human over that outcome.

Each step lands as its own PR. Steps 2 and 3 are mechanical moves; steps 4–6 change structure, but must not change output.

Checklist

• Child 1: move the inventory phase into collect_inventory → ScanInventory (mechanical). Filed as a sub-issue.
• Child 2: move the batch query into query_patches → PatchQuery (mechanical). Lands after Only scan, get <uuid> and vex fall back to the public proxy on 401/403; get search, apply, rollback, repair and vendor eject fail #647 and Chunk patch batch searches through one core helper with one set of batch limits #675, which edit the same block.
• Child 3: compute the agent selection once (discover_selected → classified_rows → partition_agent_selection → plan_kept_rows) and remove the output parameters from discover_selected by returning warnings as data.
• Child 4: one mode dispatch over Selection; delete the second run_redirect/boxed_vendor_*/download_and_apply_patches_with call of each pair.
• Child 5: render_json/render_human over the typed outcome, including the "no packages" exit. Coordinate the JSON shape with decision Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704.

Acceptance criteria

• run_scan is under 200 lines and dispatches each mode once.
• Each mode's selection and consumer run once per scan, whatever the output format.
• The scan test targets and the benchmark gate from Add a scan benchmark suite and a CI performance gate #485 stay green at every step, with no snapshot or golden JSON changes except where a child says so.

Dependencies

Children 2 and 5 wait on #647, #675 and decision #704. It relates to C12 (engine code out of the CLI) and C10/#793 (RunCtx): the phase functions should take the RunCtx when it exists.

Consolidated work — backlog review, 2026-10-08

The following standalone issues are now tracked here. Their closure consolidates scheduling; it does not mean their implementation is complete. Original reports and discussion remain linked below.

#844: Move scan's crawl, supplements and filters out of run_scan into collect_inventory

• Track the remaining scope from Move scan's crawl, supplements and filters out of run_scan into collect_inventory #844 in this issue. Explicit inventory-extraction child of the scan-phase split; one tracker can hold this step.