[JacobStephens2]

Spec #583 adds subscription Plan usage. Each machine watches its five subscription Harnesses, shows usage in the CLI and the Console, routes session Steps across [harness] routes, and ends a Command as a Paused Command instead of failing its issue. The five Tickets (#2181 to #2185) land together here, with the Spec review's fixes on top.

Closes #583

Summary

flowchart LR
    W["Harness wire frames<br/>(rate_limit_event, token_count,<br/>terminal UsageLimit)"] --> S[("~/.thirdshift/plan-usage.json")]
    R["non-billed reads<br/>(codex app-server, muse serve,<br/>claude auth status)"] --> S
    S --> V["thirdshift plan-usage / Console /plan-usage<br/>Fleet grouping, header pill"]
    S --> P{"Pass admission"}
    P -- every route held --> K["skip quietly<br/>Activity log + status banner"]
    P -- a route free --> St["per-Step routing<br/>before the Step, then on a structured stop"]
    St -- no route left --> PC["Paused Command (exit 75)<br/>Claim released without agent-failed"]

Loading

How the Tickets fit together:

src/plan_usage/            # #2181 observation, store, reads, view; #2183 Fleet
├── observation.rs         #   structured frames only → Observation
├── store.rs / read.rs     #   machine snapshot, cooldown backoff 1h→2h→4h→6h, TTL reads
├── route.rs / router.rs   # #2182 [harness]/[security] routes, max_utilization, allow_credits
├── exhaustion.rs          # #2184 "every route held" for Pass skips, pauses, banner
└── fleet.rs / view.rs     # #2183 Fleet grouping by account, offline cache, report push
src/session.rs             # #2182 per-Step routing, mid-Step clean reset, continuation
src/claim.rs, run_ending.rs, spec_run/   # #2184 Paused Command, Claim release, queued Tickets stop
src/console/plan_usage.rs  # #2183 /plan-usage, /api/v1/plan-usage, header pill
docs/guide.md, site/       # #2185 manual, how-it-works, architecture, code index

The Spec review changed these:

 factory Command with no Harness flags
-  Custom process / PR Review: harness.default only
+  Custom process / PR Review: first of harness.routes, routed per Step   (asks::choice)
+  Triage --read-machine: route settled before the sandbox starts         (plan_usage::settled_route)
 Pass skip / pause with routes = ["claude"]
-  lone route pinned: held only at 100% or a cooldown
+  lone route keeps its max_utilization and allow_credits, as the banner says
 Built with (PR and Run notification)
-  Command's first route
+  the route the implement session ran on                                  (logs::implemented_on)
 evidence of exhaustion
-  ~/.codex/sessions token_count with rate_limit_reached_type → cooldown
+  native session files report windows only; Trial native records never recorded
-  any "quota" 429 → usage limit
+  "requests per minute/second" throttles are not Plan usage
 status --json / Inbox API
+  plan_usage_banner

Evidence

Execution evidence

For each Spec finding, the reviewer's own test was added and run against the Spec branch before the fix, then again after it:

• Before: cargo test --test plan_usage_pause a_custom_process_with_no_harness_flags_routes_its_steps → FAILED: thirdshift: no allowed route has available Plan usage: claude in cooldown (five_hour) until 2096-10-02T07:06:40Z
  After: test result: ok. 1 passed (the step runs on codex: process-step-1: on codex · default model · default effort, routed by Plan usage: claude is in cooldown)
• Before: cargo test --test plan_usage_pause a_machine_reading_triage_starts_on_the_route_plan_usage_allows (with the Triage change removed) → FAILED: triage: not started: no allowed route has available Plan usage: claude in cooldown (five_hour) …
  After: test result: ok. 1 passed
• Before: cargo test --test plan_usage_routing built_with_names_the_route_the_implement_session_ran_on → FAILED: Built with claude unknown · default model · default effort <!-- thirdshift:built-with -->, although no claude session ran
  After: test result: ok. 1 passed
• Before: cargo test --test plan_usage_pause a_single_route_reserve_ceiling_skips_passes_as_the_banner_says → FAILED: left: Some(1) right: Some(0). The banner said Passes skip, but Pickup ran a Claude session.
  After: test result: ok. 1 passed
• Before: cargo test --bin thirdshift a_forged_native_codex_limit_never_marks → FAILED: assertion failed: !failure.plan_usage_exhausted
  After: test result: ok
• Before: cargo test --test plan_usage_pause status_json_carries_the_plan_usage_banner → FAILED: the JSON had no plan_usage_banner
  After: test result: ok. 1 passed
• Before: cargo test --bin thirdshift plan_usage::observation::tests → FAILED: a_per_minute_quota_throttle_is_not_plan_usage
  After: test result: ok. 5 passed

scripts/affected-tests refs/remotes/origin/main selected the site checks, the Console browser tests and the full Rust suite. This host has no C toolchain, so cargo ran in a Rocky Linux 9 container.

• npm test --prefix site: PASS.
• npm test --prefix console: PASS.
• The full Rust suite, cargo test --no-fail-fast: every test passed except six, which all depend on the container. Each of them passed when re-run in an environment that matches CI:
  • Run with an init process: process::tests (30 passed), --test setup (38 passed) and --test setup_offer (8 passed). Without one, orphaned children are never reaped, so these report "owned check process … survived".
  • Run with Python 3.12: --test bug_origins (18 passed). The container's python3 is 3.9.
  • Re-run alone, twice: --test trial (32 passed). Its a_live_plan_limit_cuts_short_a_trial_and_keeps_its_evidence gives a session only 0.5 s to be stopped after a limit, and it overran that once while the suite ran under load.
• cargo fmt --check and cargo clippy --all-targets -- -D warnings: clean.
• npm run docs:check --prefix site: clean.

Visual evidence

Fixture Plan usage only (hostname laptop-fixture): routes ["claude", "codex"] at an 85% ceiling, with claude in cooldown after its seven-day window. On the Base branch the Console has no Plan usage page, so it serves an empty 404, and there is no header pill.

Console header and Inbox, 1440×900

Console header and Inbox, 390×844

/plan-usage, 1440×900

/plan-usage, 390×844

Merge Danger

Door: two-way

Routing is opt-in: harness.routes = [] and max_utilization = 100 are the defaults, and they keep single-Harness behaviour. Reverting removes the new keys; a User config that sets them would then fail validation until they are removed. Saved plan-usage.json snapshots and the new Command-record fields (limit, resume_command, handed_back_for_pickup, stage harness/model/effort) are additive.

Blast Radius: wide

• Every factory Command now reads machine Plan usage before each Step.
• Every Pass reads it after the GitHub quota check.
• A Command whose routes are all held exits 75 as paused instead of failing.
• The Claim release on a pause puts ready-for-agent back without agent-failed.
• Custom processes and PR Reviews with no Harness flags now take harness.routes when it is set.

Unaddressed findings

Standards

• S1: cfg!(test) bypasses in Plan usage I/O (8 sites). Declined. The guards keep unit tests away from the developer's real ~/.thirdshift/plan-usage.json and User config. Injecting a snapshot source and the config would mean threading them through Router, OnMachine (src/session.rs router), harness/agy.rs credits_allowed, session/recording.rs record, command_limit.rs and status. That redesigns seams beyond this review's scope. The pure parts already take their inputs (router.rs select, exhaustion::judge) and carry unit tests, and the I/O paths are covered by the integration suites (tests/plan_usage*.rs). The one harmful consequence, a unit test writing the real ~/.thirdshift (S2), is fixed.
• S3: Fleet Plan usage repeats Fleet metrics' remote fallback, report receive guard, Refusal and handler. Declined. Lifting them into src/console/fleet/snapshot.rs would change the shipped Metrics report path (src/logs/metrics/fleet.rs, src/console/metrics.rs) as well. The two keep different snapshot types and read policies; Metrics' Capture reads once through its SavedFiles seam. A shared abstraction belongs in its own change with Metrics' tests.
• S8 (part): the "unwatched Harness is usable when installed" rule appears in router.rs select, exhaustion.rs judge and view.rs View::of. Declined. The three answer different questions: which route to take, whether every route is held, and what to display. They already share State::availability. The concrete divergence the reviewer found, latest_limit reading a window that had reset, is fixed with the shared State::used_percent_in.

Spec

• P7: plan-usage --push [<destination>] is an extra hand-run CLI. Declined. It mirrors the existing metrics --push [<destination>] (docs/guide.md:473) and sends the same payload as the post-Command push the Spec asks for ("post-Command console report pushes include the reporting host's local Plan usage snapshot"). That lets a NATted machine report without running a Command, and it shares src/console/report.rs with the metrics push.

Security review outcome

No unaddressed introduced findings.

Review coverage

Both reviewers read every changed file at least at the hunk level. site/docs/index.html is generated from docs/guide.md and was intentionally not read; npm run docs:check --prefix site passes. No changed file was left unread.

Tickets

• Record and inspect local Plan usage across subscription Harnesses and User config routes #2181 landed with Record and inspect local Plan usage across subscription Harnesses and User config routes #2198
• Console /plan-usage, Fleet shared-login grouping, console report push, and header warning pill #2182 landed with Show Plan usage across the Fleet in the CLI and Console #2204
• Route factory session Steps proactively and reactively across configured Plan usage routes #2183 landed with Route factory session Steps across configured Plan usage routes #2200
• Skip Passes and end exhausted factory Commands as Paused Commands without agent-failed #2184 landed with Skip Passes and end exhausted factory Commands as Paused Commands without agent-failed #2207
• Document Plan usage viewing and routing across the user manual, site pages, and code index #2185 landed with Document Plan usage viewing and routing across the user manual, site pages and code index #2208