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.
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/PKG-INFO +8 -5
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/README.md +7 -4
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/docs/architecture.md +75 -26
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/docs/usage.md +33 -15
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/__init__.py +1 -1
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/cli.py +151 -71
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/model.py +6 -2
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/policy.py +20 -15
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/providers/claude.py +2 -1
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/store.py +15 -6
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_handover.py +14 -3
- fairshare_cli-0.1.2/tests/test_limit_wait.py +204 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_pickup.py +15 -6
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_wait.py +22 -12
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/.githooks/pre-commit +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/.github/workflows/publish.yml +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/.github/workflows/tests.yml +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/.gitignore +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/CLAUDE.md +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/CONTRIBUTING.md +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/LICENSE +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/docs/terms-and-limits.md +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/pyproject.toml +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/browser.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/hub.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/plans/__init__.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/plans/claude-max.toml +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/plans/claude-pro.toml +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/plans/claude-ultra.toml +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/providers/__init__.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/providers/base.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/providers/claude_skill/SKILL.md +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/src/fairshare/session.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.321/auth-status-logged-out.json +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.321/auth-status-pro.json +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/auth-status-logged-out.exit +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/auth-status-logged-out.json +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/auth-status-pro.json +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/note-stream.jsonl +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/transcript.jsonl +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/usage-logged-out.exit +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/usage-logged-out.json +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/usage-week-hot.json +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/usage-week-hot.txt +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/fixtures/claude-2.1.322/usage.txt +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_canaries.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_checkpoints.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_claude_and_store.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_continuation.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_degrade.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_discovery.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_fix.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_honest.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_hooks.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_hub.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_launcher.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_note_progress.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_pause.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_policy.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_prefer.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_session.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_signin.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_skill.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_spend.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_trust.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_usage.py +0 -0
- {fairshare_cli-0.1.1 → fairshare_cli-0.1.2}/tests/test_watch.py +0 -0
- {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.
|
|
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
|
|
84
|
-
|
|
85
|
-
|
|
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
|
|
60
|
-
|
|
61
|
-
|
|
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) ──►
|
|
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
|
|
77
|
-
|
|
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
|
|
496
|
-
once the limit resets (observed 2.1.322,
|
|
497
|
-
waiting keeps the whole context and costs
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
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 ·
|
|
524
|
-
! fairshare pickup to
|
|
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
|
|
543
|
-
|
|
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
|
|
571
|
-
|
|
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
|
|
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
|
-
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
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).
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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)
|
|
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` (
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
full
|
|
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.
|
|
2
|
+
__version__ = "0.1.2"
|