fairshare-cli 0.1.1__py3-none-any.whl

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.
@@ -0,0 +1,55 @@
1
+ ---
2
+ name: fairshare
3
+ description: Use in a session started by fairshare (which spreads work across several accounts) to start background workers for big or long work, keep `fairshare watch` running while they live, act on fairshare's usage warnings, write and request checkpoints, pick up stopped work, hand off, and run `/fairshare` commands.
4
+ ---
5
+
6
+ # Working under fairshare
7
+
8
+ fairshare runs this session on one of several accounts and says when an account is nearly
9
+ spent. The main session (you, unless you were told you are a worker) decides for itself and its
10
+ workers. A worker makes no account decisions: it checkpoints when asked.
11
+
12
+ ## Worker or subagent
13
+ - Small, short work: a subagent (the Agent tool). fairshare tells subagents nothing; if the
14
+ limit hits, you and the subagent stop together and one pickup covers both.
15
+ - Big or long work: a worker, a background session that can be stopped, moved and relaunched:
16
+ `fairshare worker --model <model> --effort <level> "<prompt>"` (optional `--account ID`,
17
+ `--name NAME`). It prints the worker's name and session id.
18
+ - Always name a model and an effort fitted to the worker's task: mechanical work (renames,
19
+ field additions, doc edits) gets a cheaper model and a lower effort; design work or changes
20
+ across many files get the strongest model at high effort. For a model without effort levels,
21
+ pass `--effort none`.
22
+ - A worker needs the folder trusted on its account. If another account trusts it,
23
+ `fairshare trust` copies that trust (it never creates trust).
24
+
25
+ ## While workers live
26
+ - Keep `fairshare watch` running as a background command. It exits when something concerns you
27
+ (your account near its limit, a worker's checkpoint, a worker stopped by its limit, ended or
28
+ idle) and prints one line per event. Act on them, then start `fairshare watch` again.
29
+ - `fairshare checkpoint --show <worker name>` prints a worker's note.
30
+ - A worker stopped by its limit: watch says when that limit resets, and Claude Code resumes the
31
+ worker by itself then, with its whole context. If that is soon, let it wait; otherwise
32
+ `fairshare pickup <its session id>` continues it on the best account now, in the background.
33
+ - To stop a worker, use your own tools (`claude stop`, or a message to it).
34
+
35
+ ## When fairshare warns you
36
+ A warning names the account, its percent, when that window resets and the best other account.
37
+ - Little work left: carry on.
38
+ - Otherwise, at the next stopping point: `fairshare checkpoint --request all` (your workers
39
+ checkpoint), `fairshare checkpoint "<where you stand>"`, then `fairshare pickup`: this same
40
+ session continues on the best account, with its whole context.
41
+ - For a lean start instead, `fairshare handoff "<what was done, what is next, open decisions,
42
+ files touched>"`: a fresh session starts on the best account and reads that note first.
43
+
44
+ ## Checkpoints
45
+ - `fairshare checkpoint "<what is done, what is next>"` appends to this session's note.
46
+ - `fairshare checkpoint --request <worker name | session id | all>` asks workers for one; each
47
+ hears it at its next step.
48
+
49
+ ## `/fairshare` and `! fairshare`
50
+ They are the same verbs with the same arguments. `! fairshare ...` (typed by the user) runs at
51
+ once, costs no turn and works when the account is out. `/fairshare ...` comes to you: on
52
+ `/fairshare <args>`, run `fairshare <args>` exactly as given, except `handoff` with no note:
53
+ write the note yourself and run `fairshare handoff "<note>" <the same flags>`.
54
+
55
+ Never run fairshare commands for a subagent: they are for the main session and its workers.
fairshare/session.py ADDED
@@ -0,0 +1,113 @@
1
+ """Run one interactive child session and stay out of its way. Provider-neutral: a launch, and a
2
+ pickup that stops the child with SIGTERM and starts the next account, both use it."""
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import select
7
+ import signal
8
+ import subprocess
9
+ import sys
10
+ import time
11
+ from typing import Callable
12
+
13
+ PICKUP = -1 # run_child's answer when it stopped the child for a pickup (not an exit code)
14
+ STOP_WAIT = 10.0 # seconds a child stopped for a pickup gets to exit on SIGTERM; then SIGKILL
15
+
16
+
17
+ def run_child(cmd: list[str], env: dict[str, str],
18
+ on_request: Callable[[int], bool] | None = None) -> int:
19
+ """Start `cmd` as a child and wait for it; return its exit code (128 + n when signal n killed
20
+ it). The terminal sends Ctrl-C, Ctrl-\\ and Ctrl-Z to the whole foreground process group, so
21
+ the child already receives them; this parent must only survive and keep waiting:
22
+ - SIGINT, SIGQUIT, SIGTSTP do nothing here (handlers, not SIG_IGN, so the child still starts
23
+ with the default action for each);
24
+ - when the child stops, this process stops too (SIGSTOP), so the shell gets its prompt back;
25
+ when it is continued (`fg`), the child is continued and the wait resumes;
26
+ - SIGTERM and SIGHUP are forwarded to the child.
27
+ With `on_request`, SIGUSR1 asks for a pickup: `on_request(child pid)` is called in the wait
28
+ (not in the signal handler); False goes back to waiting, True stops the child (SIGTERM, then
29
+ SIGKILL after STOP_WAIT seconds) and returns PICKUP. Without it SIGUSR1 keeps its default.
30
+ The wait sleeps on a pipe that every signal wakes (`signal.set_wakeup_fd`), so a request
31
+ arriving at any moment is seen and an exit status is never lost."""
32
+ child: subprocess.Popen | None = None
33
+ asked = False
34
+
35
+ def forward(signum, _frame):
36
+ if child is not None and child.returncode is None:
37
+ try:
38
+ os.kill(child.pid, signum)
39
+ except ProcessLookupError:
40
+ pass
41
+
42
+ def request(_signum, _frame):
43
+ nonlocal asked
44
+ asked = True
45
+
46
+ handlers = {signal.SIGINT: lambda *_: None, signal.SIGQUIT: lambda *_: None,
47
+ signal.SIGTSTP: lambda *_: None, signal.SIGCHLD: lambda *_: None,
48
+ signal.SIGTERM: forward, signal.SIGHUP: forward,
49
+ **({signal.SIGUSR1: request} if on_request else {})}
50
+ wake_r, wake_w = os.pipe()
51
+ for fd in (wake_r, wake_w):
52
+ os.set_blocking(fd, False)
53
+ saved = {s: signal.signal(s, h) for s, h in handlers.items()}
54
+ saved_fd = signal.set_wakeup_fd(wake_w)
55
+ try:
56
+ try:
57
+ child = subprocess.Popen(cmd, env=env)
58
+ except OSError as e:
59
+ print(f"fairshare: cannot start {cmd[0]}: {e.strerror}", file=sys.stderr)
60
+ return 127 if isinstance(e, FileNotFoundError) else 126
61
+ while True:
62
+ pid, status = os.waitpid(child.pid, os.WNOHANG | os.WUNTRACED)
63
+ if pid == 0:
64
+ if asked:
65
+ asked = False
66
+ if on_request(child.pid):
67
+ _stop(child.pid)
68
+ child.returncode = PICKUP
69
+ return PICKUP
70
+ continue
71
+ select.select([wake_r], [], []) # until a signal (SIGCHLD included)
72
+ _drain(wake_r)
73
+ continue
74
+ if os.WIFSTOPPED(status):
75
+ os.kill(os.getpid(), signal.SIGSTOP) # returns once something continues us
76
+ os.kill(child.pid, signal.SIGCONT)
77
+ continue
78
+ child.returncode = (os.WEXITSTATUS(status) if os.WIFEXITED(status)
79
+ else 128 + os.WTERMSIG(status))
80
+ return child.returncode
81
+ finally:
82
+ signal.set_wakeup_fd(saved_fd)
83
+ for s, h in saved.items():
84
+ signal.signal(s, h)
85
+ os.close(wake_r)
86
+ os.close(wake_w)
87
+
88
+
89
+ def _drain(fd: int) -> None:
90
+ try:
91
+ while os.read(fd, 512):
92
+ pass
93
+ except BlockingIOError:
94
+ pass
95
+
96
+
97
+ def _stop(pid: int) -> None:
98
+ """SIGTERM the child and reap it; SIGKILL when it has not exited after STOP_WAIT seconds."""
99
+ try:
100
+ os.kill(pid, signal.SIGTERM)
101
+ except ProcessLookupError:
102
+ pass
103
+ end = time.monotonic() + STOP_WAIT
104
+ while time.monotonic() < end:
105
+ done, status = os.waitpid(pid, os.WNOHANG)
106
+ if done and not os.WIFSTOPPED(status):
107
+ return
108
+ time.sleep(0.05)
109
+ try:
110
+ os.kill(pid, signal.SIGKILL)
111
+ except ProcessLookupError:
112
+ pass
113
+ os.waitpid(pid, 0)