fairshare-cli 0.1.1__tar.gz → 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/PKG-INFO +8 -5
  2. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/README.md +7 -4
  3. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/docs/architecture.md +75 -26
  4. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/docs/usage.md +33 -15
  5. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/__init__.py +1 -1
  6. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/cli.py +151 -71
  7. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/model.py +6 -2
  8. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/policy.py +20 -15
  9. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/providers/claude.py +2 -1
  10. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/store.py +15 -6
  11. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_handover.py +14 -3
  12. fairshare_cli-0.1.2/tests/test_limit_wait.py +204 -0
  13. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_pickup.py +15 -6
  14. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_wait.py +22 -12
  15. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/.githooks/pre-commit +0 -0
  16. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/.github/workflows/publish.yml +0 -0
  17. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/.github/workflows/tests.yml +0 -0
  18. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/.gitignore +0 -0
  19. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/CLAUDE.md +0 -0
  20. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/CONTRIBUTING.md +0 -0
  21. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/LICENSE +0 -0
  22. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/docs/terms-and-limits.md +0 -0
  23. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/pyproject.toml +0 -0
  24. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/browser.py +0 -0
  25. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/hub.py +0 -0
  26. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/plans/__init__.py +0 -0
  27. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/plans/claude-max.toml +0 -0
  28. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/plans/claude-pro.toml +0 -0
  29. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/plans/claude-ultra.toml +0 -0
  30. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/providers/__init__.py +0 -0
  31. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/providers/base.py +0 -0
  32. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/providers/claude_skill/SKILL.md +0 -0
  33. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/session.py +0 -0
  34. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.321/auth-status-logged-out.json +0 -0
  35. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.321/auth-status-pro.json +0 -0
  36. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/auth-status-logged-out.exit +0 -0
  37. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/auth-status-logged-out.json +0 -0
  38. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/auth-status-pro.json +0 -0
  39. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/note-stream.jsonl +0 -0
  40. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/transcript.jsonl +0 -0
  41. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/usage-logged-out.exit +0 -0
  42. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/usage-logged-out.json +0 -0
  43. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/usage-week-hot.json +0 -0
  44. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/usage-week-hot.txt +0 -0
  45. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/usage.txt +0 -0
  46. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_canaries.py +0 -0
  47. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_checkpoints.py +0 -0
  48. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_claude_and_store.py +0 -0
  49. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_continuation.py +0 -0
  50. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_degrade.py +0 -0
  51. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_discovery.py +0 -0
  52. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_fix.py +0 -0
  53. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_honest.py +0 -0
  54. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_hooks.py +0 -0
  55. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_hub.py +0 -0
  56. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_launcher.py +0 -0
  57. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_note_progress.py +0 -0
  58. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_pause.py +0 -0
  59. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_policy.py +0 -0
  60. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_prefer.py +0 -0
  61. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_session.py +0 -0
  62. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_signin.py +0 -0
  63. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_skill.py +0 -0
  64. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_spend.py +0 -0
  65. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_trust.py +0 -0
  66. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_usage.py +0 -0
  67. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_watch.py +0 -0
  68. {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_workers.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: fairshare-cli
3
- Version: 0.1.1
3
+ Version: 0.1.2
4
4
  Summary: One assistant across several AI-assistant subscriptions: shared history and settings, each session started on the account whose budget is best used now.
5
5
  Project-URL: Homepage, https://github.com/Dongli99/fairshare
6
6
  Project-URL: Issues, https://github.com/Dongli99/fairshare/issues
@@ -80,9 +80,11 @@ transcripts, memory, settings, CLAUDE.md and skills. Before you run it, know tha
80
80
  - `fairshare` starts a session on the best account. `fairshare run <args>` passes the arguments
81
81
  to Claude Code unchanged; `fairshare run -a ID` starts that account instead.
82
82
  - `fairshare status` lists the accounts, best first, with their usage and live sessions.
83
- - When an account hits its limit mid-session, fairshare checks it really is out. If the limit
84
- resets soon (30 minutes by default), Claude Code resumes the session by itself. Otherwise the
85
- same session continues on the best other account, with its whole context.
83
+ - When an account hits its limit mid-session, fairshare checks it really is out, then leaves
84
+ the session for Claude Code to resume by itself at the reset, with its whole context. A line
85
+ and the status bar say which limit, when it resets, and the best account that can take work;
86
+ `! fairshare pickup` moves the session there now. `resume_wait_minutes` makes that move
87
+ automatic. A session is never resumed on an account that is out.
86
88
  - Inside a session, `! fairshare pickup` moves it now, `! fairshare handoff` starts a fresh
87
89
  session from a written note, and `! fairshare` starts a fresh session with nothing carried
88
90
  over (a *switch*).
@@ -106,7 +108,8 @@ used. Capacity is the plan's size (Pro = 1).
106
108
 
107
109
  - If the short (5-hour) window is nearly full and not resetting within the hour, the score is
108
110
  scaled by what is left of that window.
109
- - An account whose week is spent ranks below every usable account.
111
+ - An account whose week or short window is spent ranks below every usable account, however soon
112
+ it resets: it cannot take work until then.
110
113
 
111
114
  Usage comes from Claude Code's own local `/usage` command, asked for every account at each
112
115
  launch (no model call, nothing spent), and from its status line during a session. The rule is
@@ -56,9 +56,11 @@ transcripts, memory, settings, CLAUDE.md and skills. Before you run it, know tha
56
56
  - `fairshare` starts a session on the best account. `fairshare run <args>` passes the arguments
57
57
  to Claude Code unchanged; `fairshare run -a ID` starts that account instead.
58
58
  - `fairshare status` lists the accounts, best first, with their usage and live sessions.
59
- - When an account hits its limit mid-session, fairshare checks it really is out. If the limit
60
- resets soon (30 minutes by default), Claude Code resumes the session by itself. Otherwise the
61
- same session continues on the best other account, with its whole context.
59
+ - When an account hits its limit mid-session, fairshare checks it really is out, then leaves
60
+ the session for Claude Code to resume by itself at the reset, with its whole context. A line
61
+ and the status bar say which limit, when it resets, and the best account that can take work;
62
+ `! fairshare pickup` moves the session there now. `resume_wait_minutes` makes that move
63
+ automatic. A session is never resumed on an account that is out.
62
64
  - Inside a session, `! fairshare pickup` moves it now, `! fairshare handoff` starts a fresh
63
65
  session from a written note, and `! fairshare` starts a fresh session with nothing carried
64
66
  over (a *switch*).
@@ -82,7 +84,8 @@ used. Capacity is the plan's size (Pro = 1).
82
84
 
83
85
  - If the short (5-hour) window is nearly full and not resetting within the hour, the score is
84
86
  scaled by what is left of that window.
85
- - An account whose week is spent ranks below every usable account.
87
+ - An account whose week or short window is spent ranks below every usable account, however soon
88
+ it resets: it cannot take work until then.
86
89
 
87
90
  Usage comes from Claude Code's own local `/usage` command, asked for every account at each
88
91
  launch (no model call, nothing spent), and from its status line during a session. The rule is
@@ -19,7 +19,8 @@ providers/<p>.account_status (once per command, in parallel) ──────
19
19
  statusLine ──► capture ──► store.note_session (sessions/<id>.json: + model, effort, cost series), bar
20
20
  └──► stale? ──► detached `fairshare probe <id>` ──► read_usage ──► store
21
21
  StopFailure (rate_limit) ──► hook stop-failure ──► stranded record, probe, SIGUSR1 ──► launcher
22
- launcher (run_child) ◄── SIGUSR1 ──► confirm (survey) ──► reset soon? leave it (waiting_until)
22
+ launcher (run_child) ◄── SIGUSR1 ──► confirm (survey) ──► hold the limit (limits) ──► wait for the
23
+ reset (default; waiting_until, one line) or, opted in, move:
23
24
  └──► stop child ──► countdown ──► resume the same id (pickup)
24
25
  └──► stop child ──► [headless note turn] ──► fresh (handoff)
25
26
  └──► stop child ──► fresh, no prompt (switch)
@@ -73,8 +74,10 @@ doctor --fix ──► hub.present / accounts.toml `hub` ──► hub.check ─
73
74
  7. **One ordering, not tiers.** The first version split accounts into eligible and blocked and
74
75
  sorted the blocked by their short reset. Review showed that threw the score away
75
76
  across the boundary and mis-ranked spent weeks. Now a nearly-full short window scales the
76
- score (a soft preference) and a spent week sets it to `-hours until reset` (a hard fact,
77
- below any usable account). `Verdict.eligible` survives only so the CLI can report it.
77
+ score (a soft preference) and a spent window, the week or the short one (both at
78
+ `long_exhausted_pct`), sets it to `-hours until the later of them resets` (a hard fact,
79
+ below any usable account; decision 25). `Verdict.eligible` survives only so the CLI can
80
+ report it.
78
81
 
79
82
  8. **Volatile facts live in one place.** A provider renames commands, flags, environment
80
83
  variables, files, JSON fields, window names and plans, and adds or drops subscriptions. Each
@@ -492,18 +495,17 @@ doctor --fix ──► hub.present / accounts.toml `hub` ──► hub.check ─
492
495
  session reading the transcript; now it is **the same session, resumed under its own id**
493
496
  on the best account, with its model and effort (decision 23). A session that has time may
494
497
  write a checkpoint first (decision 22), or hand off to a fresh session (decision 23).
495
- - **Reset-aware.** Claude Code resumes a session its limit stopped by itself,
496
- once the limit resets (observed 2.1.322, 2026-11-11; `RESUMES_AT_RESET` in the adapter):
497
- waiting keeps the whole context and costs no re-read, which beats a pickup when the reset
498
- is near. So the launcher, after confirming an automatic request, finds when the limiting
499
- window resets (`_limit_reset`: the latest reset among the plan windows at their limit, a
500
- week at `long_exhausted_pct`, a short window at `short_hot_pct`). Within
501
- `resume_wait_minutes` (under `[policy]`, default 30, 0 = always pick up, refused below 0)
502
- it does not stop the child: it writes `waiting_until` on the session record, prints
503
- nothing (the session owns the terminal) and goes back to waiting. Beyond it, the pickup
504
- goes on as below. A manual pickup always moves. Background sessions have no launcher:
505
- watch's stranded-worker line adds `resets <clock> (Claude Code resumes it then)` and the
506
- main session decides.
498
+ - **Reset-aware** (amended by decision 25: waiting is now the default). Claude Code
499
+ resumes a session its limit stopped by itself, once the limit resets (observed 2.1.322,
500
+ 2026-11-11; `RESUMES_AT_RESET` in the adapter): waiting keeps the whole context and costs
501
+ no re-read. So the launcher, after confirming an automatic request, finds which limit
502
+ holds the account and when it lifts (`_limit`: of the plan windows at their limit, a week
503
+ at `long_exhausted_pct`, a short window at `short_hot_pct`, the one that resets last).
504
+ Unless a move is opted in (`resume_wait_minutes`, decision 25) it does not stop the
505
+ child: it writes `waiting_until` on the session record, says one line (decision 25) and
506
+ goes back to waiting. A manual pickup always moves, to an account that can take work.
507
+ Background sessions have no launcher: watch's stranded-worker line adds `resets <clock>
508
+ (Claude Code resumes it then)` and the main session decides.
507
509
  - **The session map.** capture keeps one small record per session in the state folder
508
510
  (`sessions/<id>.json`, atomic, under a lock): account, folder, transcript path, last seen,
509
511
  and when its limit stopped it. Written only when new or changed or last seen a minute ago;
@@ -520,8 +522,9 @@ doctor --fix ──► hub.present / accounts.toml `hub` ──► hub.check ─
520
522
  pid must never be signalled.
521
523
  - **The bar.** While the session's record is stranded and the policy says its account cannot
522
524
  take work, capture appends a red `out · ! fairshare pickup` (on its own line after the
523
- user's `--then` line); while it waits for the tool's own resume, `out · resumes <clock> ·
524
- ! fairshare pickup to move now`. Numbers newer than the stop that say the account can work
525
+ user's `--then` line); while it waits for the tool's own resume, `out · <span> limit ·
526
+ resumes <clock> · ! fairshare pickup moves it to <best> now` (`no account can take work
527
+ now` when none can, by the local snapshots). Numbers newer than the stop that say the account can work
525
528
  clear it, and the wait with it; so does a new stop.
526
529
  - **The launcher** exports `FAIRSHARE_LAUNCHER=<its pid>` to its child. On SIGUSR1 it reads
527
530
  the request (ignored unless it is for its own child's process). An automatic request is
@@ -539,8 +542,10 @@ doctor --fix ──► hub.present / accounts.toml `hub` ──► hub.check ─
539
542
  account B because <A hit its usage limit | a move was asked for>. Continue where you left
540
543
  off.`) and `FAIRSHARE_CONTINUES=<its pid>:<id>`; building those arguments clears the
541
544
  record's stranded mark and wait and leaves its account: the first capture under the same
542
- id writes B, and a new id (another account, decision 23) is linked to it. None eligible is decision 11's flow, carrying them. The launcher
543
- stays the parent, so a second limit picks up again.
545
+ id writes B, and a new id (another account, decision 23) is linked to it. None eligible
546
+ is decision 11's flow, carrying them (reached by a manual request only: an automatic one
547
+ waits instead, decision 25). The launcher stays the parent, so a second limit picks up
548
+ again.
544
549
  - **The manual command.** `fairshare pickup [SESSION] [--bg] [--model M] [--effort E] [-a
545
550
  ID]` (the flags override the record; `-a` skips the ranking, keeps the trust check, and is
546
551
  checked before anything is asked of a launcher). Inside a session with no
@@ -567,8 +572,11 @@ doctor --fix ──► hub.present / accounts.toml `hub` ──► hub.check ─
567
572
  cost series, and the original keeps its account, its workers and its line in `status`
568
573
  (no `moved_to`); the tool's own copy of a stranded session takes its place as a resume
569
574
  under a new id does.
570
- None eligible and able: exit 1, naming which were eligible and why trust could not be had. A session whose
571
- account can still work is picked up anyway, with one note line: moving is a valid wish.
575
+ None eligible and able: exit 1, naming which were eligible and why trust could not be
576
+ had. None eligible at all (without `-a`), in every form of the command: `no account can
577
+ take work now; the soonest is <id>, usable at <clock>; nothing done`, exit 1, before any
578
+ launcher is asked (decision 25). A session whose account can still work is picked up
579
+ anyway, with one note line: moving is a valid wish.
572
580
  - **Never stopping others' sessions.** Only the launcher stops a session, and only its own
573
581
  child. Outside it, the old session is left as it is.
574
582
  - **The pickup prompt** (cli text, provider-neutral; only a handoff's fresh session uses
@@ -774,7 +782,7 @@ doctor --fix ──► hub.present / accounts.toml `hub` ──► hub.check ─
774
782
  from the first organization). On the same account the id stays. Model and effort carried
775
783
  over both ways. So a move costs one uncached read of the context plus the thinking
776
784
  regenerated on the new account; a resume on the same account loses nothing. This weighs
777
- for `resume_wait_minutes` (decision 19): waiting for the reset keeps both.
785
+ for waiting (decisions 19 and 25): waiting for the reset keeps both.
778
786
  - **The link.** The launcher passes `FAIRSHARE_CONTINUES=<its pid>:<old id>` to a resume
779
787
  only (not a switch, not a handoff's fresh session; an inherited value is dropped).
780
788
  Capture, the prompt and post-tool hooks and the stop-failure hook call `_continuation`
@@ -827,6 +835,45 @@ doctor --fix ──► hub.present / accounts.toml `hub` ──► hub.check ─
827
835
  - **Not built:** sizes of reserved token blocks, a "still needed" ledger, and burn rate.
828
836
  They would come from this data.
829
837
 
838
+ 25. **At a limit, wait; never resume on an account that is out** (amends decisions 7 and 19).
839
+ Seen live on 2026-11-17: an account's 5-hour window was spent with the reset 40 minutes
840
+ away; 40 was over `resume_wait_minutes` (then 30), so the launcher stopped the session to
841
+ move it, but the policy ignored a short window resetting within `grace_hours` (1), the
842
+ account still ranked best on its week, and the session was restarted on it: limit, and round
843
+ again. Two thresholds disagreed, and a spent short window was treated like a nearly full one.
844
+ - **Usable now is a rule, not a score.** A short window at `long_exhausted_pct` (the line
845
+ the week uses for "spent") makes the account ineligible until that window resets, and
846
+ ranks it with the unusable ones (`score = -hours until the later spent window resets`,
847
+ `usable_in` the same, no grace). The grace hour applies only to a nearly full window. It
848
+ lives in `policy.py`, pure, so every launch, pickup, switch and handoff follows it; the
849
+ CLI's own spent-now check (`_spent_now`) went with it.
850
+ - **Waiting is the default.** When a launcher's session is stopped by its account's limit
851
+ and a fresh survey confirms it, the launcher leaves the child for the tool's own resume
852
+ whenever the tool resumes by itself and the reset is known; it writes `waiting_until` and
853
+ says one line, once per limit (`<id> is out (<span> limit) · <tool> resumes this session
854
+ at <clock> · ! fairshare pickup moves it to <best> now`, or `no account can take work now
855
+ (the soonest: <id>, usable at <clock>)`). The line goes to the terminal the session owns,
856
+ at a moment the session is idle at its limit; the bar repeats it until the reset.
857
+ `resume_wait_minutes` (under `[policy]`, refused below 0) is now an opt-in, unset by
858
+ default: N moves the session when the reset is more than N minutes away (0: always), and
859
+ only when an account can take work with the session's model; otherwise it waits. A tool
860
+ that does not resume by itself, or a limit with no known reset, is moved as before.
861
+ - **The guard, independent of the policy.** On every confirmed automatic stop the launcher
862
+ writes the limit on the session record (`limits`: `{account: reset}`, lifted ones
863
+ dropped; `link_session` carries them to a new id). `_launch` refuses any resume
864
+ (`continues`, a copy included, `-a` included) on an account held there before its reset:
865
+ `<id>'s limit stopped this session and lifts at <clock>; not resuming it there before
866
+ then. To resume it later: fairshare run -a <id> -- --resume <session>`, exit 75. And when
867
+ a move is about to be made for a limit the record already holds (the same account stopped
868
+ the session again before its reset), the launcher stops the child and ends instead (a
869
+ STOP request): `<id> stopped this session again before its limit lifted (<span> resets
870
+ <clock>); not trying again. To resume it later: …`, exit 75. A repeated stop while
871
+ waiting is not a second try: it keeps waiting and says nothing new. `fairshare run -a
872
+ <id> -- --resume <session>`, typed by the user, is not a resume fairshare makes and is
873
+ never refused.
874
+ - **Workers** are unchanged: they have no launcher; `watch` tells the main session, which
875
+ decides.
876
+
830
877
  ## Known limits
831
878
 
832
879
  - Below the "nearly full" line, short-window usage plays no part in the ranking.
@@ -846,10 +893,12 @@ doctor --fix ──► hub.present / accounts.toml `hub` ──► hub.check ─
846
893
  from a capture is still treated as stale and the stored one kept; only the probe can lower
847
894
  it (usage can fall within a window when the provider credits some back). An idle redraw of
848
895
  unchanged values leaves the snapshot's time (decision 20).
849
- - An account at 100% of its short window that resets within `grace_hours` is eligible by the
850
- policy (for new launches). For a session the provider already stopped, pickup does not wait
851
- for that reset: a plan window spent right now confirms the pickup and shows the bar mark
852
- (`_spent_now`), and the countdown lets the user cancel and resume after the reset.
896
+ - The launcher's one line when it waits (decision 25) is printed while the tool owns the
897
+ terminal; the tool may redraw over it. Not checked live; the bar carries the same facts.
898
+ - The guard (decision 25) keys a limit by the account folder that stopped the session: a twin
899
+ folder sharing that login is not held by it (the policy still ranks the twin as spent).
900
+ - A limit with no known reset (the account left out of the survey, signed out say) is not held
901
+ and not waited for; what keeps a resume off that account is that the survey does not rank it.
853
902
  - Not yet checked live: `!` commands inheriting
854
903
  `CLAUDE_CODE_SESSION_ID`; StopFailure firing on a real limit; whether `refreshInterval` re-runs
855
904
  carry fresh `rate_limits` (fairshare assumes the last payload); `CLAUDE_PID` in a hook naming
@@ -162,18 +162,34 @@ the account hit its limit (its `StopFailure` hook, which fairshare wires in the
162
162
  the session is marked as stopped, and:
163
163
 
164
164
  - **In a session started by `fairshare`**, the launcher checks that the account really is out (it
165
- asks every account's usage again; a passing rate-limit error changes nothing). If the limit
166
- resets within `resume_wait_minutes` (default 30, `0` = always move), it leaves the session
167
- alone: Claude Code resumes it by itself at the reset, with its whole context, and the status
168
- bar reads `out · resumes 15:40 · ! fairshare pickup to move now`. Otherwise it stops the session
169
- and shows `work hit its limit (5h resets 15:40). Continuing on play in 10 s · Enter = now · c =
170
- cancel`. The same session is then resumed on the best account, in the same folder, with its
171
- model and effort, and is told in one line that it was moved. `c` stops there and prints how to
172
- resume it later (`fairshare run -a work -- --resume <id>`). Without a terminal it continues at
173
- once. The launcher stays in charge, so the next limit is handled the same way.
165
+ asks every account's usage again; a passing rate-limit error changes nothing). Then, by default,
166
+ it leaves the session alone: Claude Code resumes it by itself at the reset, with its whole
167
+ context and no re-read. One line says so once, `fairshare: work is out (5h limit) · Claude Code
168
+ resumes this session at 15:40 · ! fairshare pickup moves it to play now` (or `no account can
169
+ take work now (the soonest: play, usable at 16:10)`), and the status bar reads `out · 5h limit ·
170
+ resumes 15:40 · ! fairshare pickup moves it to play now` until the reset.
171
+ - **To move automatically instead**, set `resume_wait_minutes` under `[policy]` in
172
+ `accounts.toml`: the launcher then moves the session when the reset is more than that many
173
+ minutes away (`0` = always), and only when another account can take work; otherwise it waits as
174
+ above. A move stops the session and shows `work hit its limit (5h resets 15:40). Continuing on
175
+ play in 10 s · Enter = now · c = cancel`. The same session is then resumed on the best account,
176
+ in the same folder, with its model and effort, and is told in one line that it was moved. `c`
177
+ stops there and prints how to resume it later (`fairshare run -a work -- --resume <id>`).
178
+ Without a terminal it continues at once. The launcher stays in charge, so the next limit is
179
+ handled the same way.
180
+ - **Never back onto an account that is out.** An account whose week or short window is spent
181
+ is never chosen for a launch, pickup, switch or handoff until it resets. Independently of the
182
+ ranking, the launcher remembers which account's limit stopped a session and when it resets,
183
+ and never resumes the session there before then (`fairshare: work's limit stopped this session
184
+ and lifts at 15:40; not resuming it there before then. To resume it later: …`). If the same
185
+ limit stops a session again after a move, the launcher stops instead of trying again, with
186
+ `fairshare: work stopped this session again before its limit lifted (5h resets 15:40); not
187
+ trying again. To resume it later: fairshare run -a work -- --resume <id>`.
174
188
  - **The status bar** ends in a red `out · ! fairshare pickup` while that account cannot take work.
175
189
  Typing `! fairshare pickup` in the session asks its launcher to move it now (no check that the
176
- account is out, no wait for the reset: you asked). In a session not started by `fairshare`, it
190
+ account is out, no wait for the reset: you asked), to the best account that can take work. When
191
+ none can, it says `fairshare: no account can take work now; the soonest is play, usable at
192
+ 16:10; nothing done` and leaves the session as it is. In a session not started by `fairshare`, it
177
193
  resumes the session in the background instead (`claude --bg --resume`, on the best account that
178
194
  trusts the folder or can get that trust copied from another account; Claude Code prints how to
179
195
  attach to it; background sessions open links in the system browser).
@@ -403,11 +419,13 @@ and `leave` edit it as text, keeping your comments, with a backup each time. Key
403
419
  there is one), `capacity` (overrides the plan's;
404
420
  kept when the detected plan differs), `browser` (see [Browser per account](#browser-per-account)),
405
421
  `status_args` and `usage_args`;
406
- - `[policy]`: `launch_pause` (seconds, default 3, `0` = off), `resume_wait_minutes` (default 30,
407
- `0` = always move at a limit), `refresh_minutes` (default 5, at least 1), and the ranking's
408
- thresholds `short_hot_pct` (85: a short window this full is "nearly full"),
409
- `long_exhausted_pct` (98: a week this full cannot take work) and `grace_hours` (1: a nearly
410
- full short window resetting this soon still takes work). Every number must be finite; `nan` and `inf` are a config error.
422
+ - `[policy]`: `launch_pause` (seconds, default 3, `0` = off), `resume_wait_minutes` (unset by
423
+ default: a session stopped by its limit waits for Claude Code's own resume; a number N moves
424
+ it automatically when the reset is more than N minutes away, `0` = always), `refresh_minutes`
425
+ (default 5, at least 1), and the ranking's thresholds `short_hot_pct` (85: a short window this
426
+ full is "nearly full"), `long_exhausted_pct` (98: a week or a short window this full is spent
427
+ and cannot take work until it resets) and `grace_hours` (1: a nearly full, not spent, short
428
+ window resetting this soon still takes work). Every number must be finite; `nan` and `inf` are a config error.
411
429
 
412
430
  `status_args` replaces the sign-in check's arguments and `usage_args` the usage probe's (default
413
431
  `auth status --json` and `-p --no-session-persistence --output-format json --settings
@@ -1,2 +1,2 @@
1
1
  """fairshare: route sessions across several subscriptions by real usage."""
2
- __version__ = "0.1.1"
2
+ __version__ = "0.1.2"