[JacobStephens2]

Summary

When no route a Command may take has Plan usage left, thirdshift now pauses instead of failing:

• Scheduled Passes skip without sleeping.
• Live factory Commands end as Paused Commands.
• The issue's Claim comes off without agent-failed.

 early_skip(repo, limit, harness, security)            # every Pass, before any GitHub work
   live Experiment? → skip
   GitHub Quota wait? → skip
+  every allowed route in cooldown / at its ceiling?   # plan_usage::pass_exhaustion
+    → skip "no allowed route has available Plan usage: claude in cooldown (five_hour) until …"
+      Activity log line only when the reason changes, per Pass kind / per named Custom process

 Sessions::run_step
+  every route held before the Step starts → PlanUsagePaused (no session started)
   session stops on a structured Plan-usage frame
     next route? → start the Step again there
-    none → the SessionFailure fails the Run
+    none → PlanUsagePaused   # also for a pinned or single Harness; never from agent text

 PlanUsagePaused
+  outcome "paused", exit 75; the record keeps `limit` and `resume_command`
+  Claim: release whatever is on origin, no agent-failed
+    took ready-for-agent off → put it back (record retaken_by_pickup)
+    untrusted edit since the last Trusted ready-for-agent → needs-triage
+    Security fix → agent-failed;  Triage run → needs-triage
+  Inbox: retaken_by_pickup → Done; otherwise Needs you as Paused
+  Run notification: always saved; not emailed when retaken under email.unless_merged
+  Spec run: a Ticket's child exits 75 → start no queued Ticket; running ones finish → Spec run pauses
+  Base fix child exits 75 → its Run pauses

A banner, Plan usage: every configured route is unavailable, so scheduled Passes skip: …; earliest reset …, shows on 1 Inbox and in thirdshift status while every default route on the machine is held.

Evidence

Execution evidence

These tests failed before their fixes during review, with the output shown, and pass now:

• Before: cargo test --test plan_usage_pause a_review_run_whose_only_route_stops_at_its_limit_is_recorded_paused
assertion left == right failed … left: String("failed") right: "paused"
  After: test a_review_run_whose_only_route_stops_at_its_limit_is_recorded_paused ... ok
• Before: cargo test --test base_fix a_base_fix_that_stops_at_its_plan_usage_limit_pauses_the_run
left: Some(1) right: Some(75)
  After: test result: ok. 17 passed; 0 failed (whole base_fix suite)
• Before: cargo test --bin thirdshift plan_usage::tests::machine_exhaustion_reads_nothing_in_unit_tests (with HOME=/tmp/ts-home)
  test … FAILED (found was Some)
  After: test … ok

New and affected suites now pass:

• cargo test --test plan_usage_pause: 14 passed; 0 failed
• --test plan_usage_routing: 11 passed
• --test pass_quota: 7 passed
• --test out_of_disk: 4 passed
• --test quota_wait: 10 passed
• --test run_notification: 47 passed
• --test grok_sessions: 6 passed
• --test console a_pause_pickup_retakes_sits_in_done_beside_the_plan_usage_banner: ok
• npm test --prefix console: # pass 205 # fail 0

The full suite was run with cargo test --no-fail-fast. Its only remaining failures are sandbox tests (bin sandbox::tests, and some tests in trial, scoring, experiments and bug_origins). They fail with sandbox failed to start: socat is not on PATH on this host, and they also fail on origin/issue-583.

Updated expectations: a Run stopped by a structured usage limit now ends paused (exit 75, subject : paused). This changed tests in run_notification.rs, grok_sessions.rs and pickup_run.rs (#9 paused: …). An Eval plan-limit pause still exits 1.

Visual evidence

1 Inbox uses the same fixture in Before and After:

• The default Harness claude is in cooldown.
• Paused Numbered Issue branches after a merged or closed PR #7 has retaken_by_pickup: true.
• Paused Keeping the PR mergeable: merge the Base branch and conflict Repair #8 does not.
• The hostname is masked as factory-host.

Desktop 1440×900. Before, both pauses are in Needs you and there is no banner. After, the banner shows, #7 is in Done and #8 is in Needs you.

Mobile 390×844, showing the counts. Before: Needs you 2, Done 0. After: Needs you 1, Done 1.

Review

thirdshift-code-review was run against refs/remotes/origin/issue-583. Standards raised 12 findings and Spec raised 6. All were addressed in fcbe4489, bc1eb619 and 760f8ded, except the part listed below.

Review coverage: both reviewers read every file changed in the reviewed commit d5ed0102 except site/docs/index.html. That file is generated from docs/guide.md (npm run docs:check --prefix site passes), and the reviewers confirmed the exclusion.

Changed files the review left unread, because they were added or first changed after the review pass:

• src/child_run/execution_tests.rs
• tests/base_fix.rs (the reviewer's own test, added as written)
• tests/grok_sessions.rs
• tests/pickup_run.rs
• tests/run_notification.rs

GLOSSARY.md and src/logs/activity.rs were read only as supporting files, before their fix-up edits.

Unaddressed findings

Standards

None.

Spec

• Spec 4, partly: when several Harnesses are in cooldown, a Spec run paused by its Ticket may record a Harness other than the one that Ticket stopped on.
  • The full-window case the finding's test covers is fixed: a_spec_run_whose_ticket_pauses_at_a_full_window_records_the_stopping_harness passes.
  • What remains: plan_usage::latest_limit (src/plan_usage.rs) takes the most recent active cooldown on the machine.
  • Why: a Ticket's child Run reports its pause to the Spec run only through exit code 75 (run_ending::PAUSED_EXIT, read in child_run::Handle::ending). That is deliberately the one channel no agent can write (ADR 0031, "Only structured Harness wire-frame events … count … so an agent cannot forge a pause").
  • The child's own record still keeps its exact limit.

Security

None.

Security review outcome

No unaddressed introduced findings.

Merge Danger

Door: two-way

The new Command record field retaken_by_pickup is optional, and older readers ignore it. Reverting the change restores failing Runs, with no data migration.

Blast Radius: wide

• Every Pass now reads ~/.thirdshift/plan-usage.json before any GitHub work. A stale cooldown there skips Passes until its reset or thirdshift plan-usage --clear.
• A Run stopped by a structured usage limit now exits 75 with outcome paused instead of 1 with failed. That changes scheduler exit codes, notification subjects, and Failure limit counting, which is the point.
• A paused Scoring run now emails when Run notifications are on.

Closes #2184

Built with claude 2.1.322 · claude-opus-5-5 · high