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.
fairshare/store.py ADDED
@@ -0,0 +1,648 @@
1
+ """Where state lives. Snapshots are plain JSON, one per account, written atomically."""
2
+ from __future__ import annotations
3
+
4
+ import contextlib
5
+ import fcntl
6
+ import json
7
+ import os
8
+ import re
9
+ import shutil
10
+ import tempfile
11
+ import time
12
+ from dataclasses import replace
13
+ from pathlib import Path
14
+
15
+ from .model import Request, SessionRecord, SessionSeen, Snapshot, Window, Worker
16
+
17
+
18
+ def config_path() -> Path:
19
+ return Path(os.environ.get("FAIRSHARE_CONFIG",
20
+ Path.home() / ".config/fairshare/accounts.toml"))
21
+
22
+
23
+ def state_dir() -> Path:
24
+ return Path(os.environ.get("FAIRSHARE_STATE", Path.home() / ".local/state/fairshare"))
25
+
26
+
27
+ def load(account_id: str) -> Snapshot | None:
28
+ """The account's snapshot; None when there is none or it cannot be read. A window whose
29
+ numbers are not numbers is left out, as if never seen, so that the next probe refills it."""
30
+ try:
31
+ d = json.loads((state_dir() / "snapshots" / f"{account_id}.json").read_text())
32
+ windows = {k: Window(pct, at) for k, v in d["windows"].items() if isinstance(v, dict)
33
+ and (pct := _num(v.get("used_pct"))) is not None
34
+ and (at := _num(v.get("resets_at"))) is not None}
35
+ return Snapshot(float(d["captured_at"]), windows) if _num(d["captured_at"]) is not None \
36
+ else None
37
+ except (OSError, ValueError, KeyError, TypeError, AttributeError):
38
+ return None
39
+
40
+
41
+ def _write_json(dest: Path, name: str, data: dict) -> None:
42
+ """Write `dest/name` atomically."""
43
+ dest.mkdir(parents=True, exist_ok=True)
44
+ fd, tmp = tempfile.mkstemp(dir=dest)
45
+ with os.fdopen(fd, "w") as f:
46
+ f.write(json.dumps(data))
47
+ os.replace(tmp, dest / name)
48
+
49
+
50
+ def save(account_id: str, snap: Snapshot) -> None:
51
+ _write_json(state_dir() / "snapshots", f"{account_id}.json",
52
+ {"captured_at": snap.captured_at,
53
+ "windows": {k: vars(v) for k, v in snap.windows.items()}})
54
+
55
+
56
+ def record_subscription(account_id: str, subscription: bool, now: float) -> None:
57
+ """Remember the provider's last answer to "is this a subscription login?": a yes/no and the
58
+ time, nothing else. Failing to write only means the account is never counted as confirmed."""
59
+ try:
60
+ _write_json(state_dir() / "checks", f"{account_id}.json",
61
+ {"subscription": subscription, "checked_at": now})
62
+ except OSError:
63
+ pass
64
+
65
+
66
+ def subscription_seen(account_id: str) -> tuple[bool, float] | None:
67
+ """(answer, time) of the last successful sign-in check, or None when there never was one."""
68
+ try:
69
+ d = json.loads((state_dir() / "checks" / f"{account_id}.json").read_text())
70
+ if isinstance(d["subscription"], bool):
71
+ return d["subscription"], float(d["checked_at"])
72
+ except (OSError, ValueError, KeyError, TypeError):
73
+ pass
74
+ return None
75
+
76
+
77
+ def save_preference(account_id: str, until: float) -> None:
78
+ _write_json(state_dir(), "prefer.json", {"account": account_id, "until": until})
79
+
80
+
81
+ def clear_preference() -> None:
82
+ with contextlib.suppress(FileNotFoundError):
83
+ (state_dir() / "prefer.json").unlink()
84
+
85
+
86
+ def preference(now: float) -> tuple[str, float] | None:
87
+ """(account id, until) of the user's timed preference, None when there is none or it ended."""
88
+ try:
89
+ d = json.loads((state_dir() / "prefer.json").read_text())
90
+ if isinstance(d["account"], str) and float(d["until"]) > now:
91
+ return d["account"], float(d["until"])
92
+ except (OSError, ValueError, KeyError, TypeError):
93
+ pass
94
+ return None
95
+
96
+
97
+ SAME_WINDOW_S = 3600 # resets this close together belong to the same window
98
+ PROBE_ROUNDING = 1.0 # the probe's text gives whole percents: a fall this small is rounding
99
+
100
+
101
+ def merge(old: Snapshot | None, fresh: dict[str, Window], now: float,
102
+ probe: bool = False) -> Snapshot:
103
+ """A payload may omit a window that is still running; keep the old one until it expires.
104
+ Idle sessions redraw with the last values they received, so a lower value for the same
105
+ window from a redraw is stale: keep the stored one. Usage can still fall within a window
106
+ (the provider credits some back), and the provider's own usage probe (`probe`) is current
107
+ by construction: its lower value for the same window is taken when it falls by more than
108
+ rounding, under the stored reset (the probe gives the reset to the minute only). A fresh
109
+ window already past its reset is a redraw from before the reset: never taken. The
110
+ snapshot's time says when its numbers were last known to be current: it moves when a
111
+ window's value or reset changed or a window appeared, or when they came from a probe, never
112
+ for a redraw of equal values, so idle redraws cannot make it look fresh."""
113
+ kept = {k: w for k, w in (old.windows if old else {}).items() if w.resets_at > now}
114
+ taken = {}
115
+ for k, w in fresh.items():
116
+ if w.resets_at <= now: # a redraw of a window that already reset
117
+ continue
118
+ was = kept.get(k)
119
+ if was and w.used_pct < was.used_pct and abs(w.resets_at - was.resets_at) <= SAME_WINDOW_S:
120
+ if not probe or was.used_pct - w.used_pct <= PROBE_ROUNDING:
121
+ continue # stale, or rounding
122
+ w = Window(w.used_pct, was.resets_at) # credited back
123
+ taken[k] = w
124
+ changed = any(kept.get(k) != w for k, w in taken.items())
125
+ return Snapshot(now if probe or changed or old is None else old.captured_at,
126
+ {**kept, **taken})
127
+
128
+ def record(account_id: str, fresh: dict[str, Window], now: float,
129
+ probe: bool = False) -> Snapshot:
130
+ """Merge `fresh` into the stored snapshot and save it, holding the account's lock, so two
131
+ captures arriving together cannot both read the old snapshot and the last one win. `probe`:
132
+ the windows came from the provider's own usage probe (see `merge`)."""
133
+ dest = state_dir() / "snapshots"
134
+ dest.mkdir(parents=True, exist_ok=True)
135
+ with open(dest / f"{account_id}.lock", "w") as lock:
136
+ fcntl.flock(lock, fcntl.LOCK_EX)
137
+ snap = merge(load(account_id), fresh, now, probe)
138
+ save(account_id, snap)
139
+ return snap
140
+
141
+
142
+ def claim_probe(account_id: str, now: float, max_age: float) -> bool:
143
+ """Whether a background usage probe for the account may start now; if so, it is marked as
144
+ started. One whose mark is under `max_age` seconds old is taken to be running still."""
145
+ dest = state_dir() / "probes"
146
+ dest.mkdir(parents=True, exist_ok=True)
147
+ mark = dest / f"{account_id}.started"
148
+ with locked(dest / ".lock"):
149
+ try:
150
+ if now - mark.stat().st_mtime < max_age:
151
+ return False
152
+ except FileNotFoundError:
153
+ pass
154
+ mark.touch()
155
+ os.utime(mark, (now, now))
156
+ return True
157
+
158
+
159
+ SESSION_KEEP_S = 7 * 24 * 3600 # a session record unseen this long is dropped
160
+ SESSION_WRITE_S = 60 # an unchanged record is rewritten at most this often
161
+ _SESSION_ID = re.compile(r"[\w][\w.-]*") # a session id is also a file name here
162
+
163
+
164
+ def _sessions() -> Path:
165
+ return state_dir() / "sessions"
166
+
167
+
168
+ def _num(v: object) -> float | None:
169
+ return float(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else None
170
+
171
+
172
+ def _text(v: object) -> str | None:
173
+ return v if isinstance(v, str) and v else None
174
+
175
+
176
+ def _costs(v: object) -> list:
177
+ """A cost series as stored; [] for anything that is not one."""
178
+ if not isinstance(v, list) or not all(
179
+ isinstance(s, list) and s and all(isinstance(p, list) and len(p) == 2
180
+ and _num(p[0]) is not None
181
+ and _num(p[1]) is not None for p in s) for s in v):
182
+ return []
183
+ return v
184
+
185
+
186
+ COST_POINT_S = 300 # a new cost point once the last one is this old (the latest value is kept)
187
+ COST_KEEP_S = 7200 # cost points older than this are dropped, one kept before as a baseline
188
+
189
+
190
+ def add_cost(series: list, t: float, cost: float) -> list:
191
+ """`series` (oldest first: segments of [time, cost] points) with the running cost `cost` seen
192
+ at `t`. A cost that moved adds a point when the last one is COST_POINT_S old or more, else
193
+ becomes the last point's value (a segment's first point is never changed: it is the base);
194
+ a cost lower than the last means the session started counting again: a new segment from it,
195
+ never a negative spend. Points older than COST_KEEP_S go, except the one before the oldest
196
+ kept (the base its rise is measured from) and the latest value."""
197
+ segs = [[list(p) for p in seg] for seg in series]
198
+ last = segs[-1][-1] if segs else None
199
+ if last is None or cost < last[1]:
200
+ segs.append([[t, cost]])
201
+ elif cost > last[1]:
202
+ if len(segs[-1]) == 1 or t - last[0] >= COST_POINT_S:
203
+ segs[-1].append([t, cost])
204
+ else:
205
+ last[1] = cost
206
+ cut, kept = t - COST_KEEP_S, []
207
+ for i, seg in enumerate(segs):
208
+ while len(seg) >= 2 and seg[1][0] <= cut:
209
+ seg.pop(0)
210
+ if seg[-1][0] > cut or i == len(segs) - 1:
211
+ kept.append(seg)
212
+ return kept
213
+
214
+
215
+ def spend(series: list, start: float, end: float) -> float | None:
216
+ """The cost rise of a session inside (start, end]: each rise between two points counts at
217
+ the later point's time (at most COST_POINT_S late). None when the session has no cost data."""
218
+ if not series:
219
+ return None
220
+ return sum(q[1] - p[1] for seg in series for p, q in zip(seg, seg[1:]) if start < q[0] <= end)
221
+
222
+
223
+ def total_cost(series: list) -> float | None:
224
+ """A session's cost as far as the series knows: the last value of each segment (each one
225
+ counts from zero again)."""
226
+ return sum(seg[-1][1] for seg in series) if series else None
227
+
228
+
229
+ def _drawn(v: object) -> dict:
230
+ """Drawn windows as stored; {} for anything that is not them."""
231
+ if not isinstance(v, dict) or not all(
232
+ isinstance(ws, dict) and all(isinstance(w, list) and len(w) == 2
233
+ and all(_num(x) is not None for x in w)
234
+ for w in ws.values()) for ws in v.values()):
235
+ return {}
236
+ return v
237
+
238
+
239
+ def _read_session(path: Path) -> SessionRecord | None:
240
+ try:
241
+ d = json.loads(path.read_text())
242
+ return SessionRecord(path.stem, str(d["account"]), d.get("cwd"), d.get("transcript"),
243
+ float(d["seen"]), None if d.get("stranded_at") is None
244
+ else float(d["stranded_at"]), _text(d.get("role")),
245
+ _text(d.get("parent")),
246
+ _num(d.get("checkpoint_requested")), _num(d.get("request_said")),
247
+ d["warned"] if isinstance(d.get("warned"), dict) else {},
248
+ d["reported"] if isinstance(d.get("reported"), dict) else {},
249
+ _text(d.get("model")), _text(d.get("model_name")),
250
+ _text(d.get("effort")), _num(d.get("waiting_until")),
251
+ _costs(d.get("costs")), _text(d.get("continues")),
252
+ _text(d.get("moved_to")), _drawn(d.get("drawn")))
253
+ except (OSError, ValueError, KeyError, TypeError, AttributeError):
254
+ return None
255
+
256
+
257
+ _SESSION_BASE = ("account", "cwd", "transcript", "seen", "stranded_at")
258
+
259
+
260
+ def _write_session(dest: Path, rec: SessionRecord) -> None:
261
+ """The record's file: the base fields always, the others only when set."""
262
+ _write_json(dest, f"{rec.id}.json", {k: v for k, v in vars(rec).items()
263
+ if k in _SESSION_BASE or (k != "id" and v)})
264
+
265
+
266
+ def session(session_id: str) -> SessionRecord | None:
267
+ """The record of one session, or None."""
268
+ if not _SESSION_ID.fullmatch(session_id):
269
+ return None
270
+ return _read_session(_sessions() / f"{session_id}.json")
271
+
272
+
273
+ def sessions() -> list[SessionRecord]:
274
+ """Every session record that reads."""
275
+ found = sorted(_sessions().glob("*.json")) if _sessions().is_dir() else []
276
+ return [r for p in found if (r := _read_session(p))]
277
+
278
+
279
+ def _drop_old(dest: Path, now: float) -> None:
280
+ for p in dest.glob("*.json"):
281
+ if (r := _read_session(p)) and now - r.seen > SESSION_KEEP_S:
282
+ with contextlib.suppress(OSError):
283
+ p.unlink()
284
+
285
+
286
+ def note_session(seen: SessionSeen, account_id: str, now: float,
287
+ stranded: bool | None = None) -> SessionRecord | None:
288
+ """Record that `seen` runs on `account_id`, keeping its folder and transcript (a field the
289
+ provider left out keeps its old value) and every other field. `stranded` True marks it
290
+ stopped by its account's limit now, False clears that, None leaves it. Written only when it
291
+ is new or changed, or last seen SESSION_WRITE_S ago or more, so a redraw costs no write;
292
+ a change of `stranded` either way also ends a wait for the provider's own resume;
293
+ each write drops the records unseen for SESSION_KEEP_S. Under a lock: a hook and a usage
294
+ hook may arrive together. None for an id that cannot be a file name. A model `seen` names
295
+ replaces the known model, display name and effort together (the user may change them
296
+ mid-session); none named keeps them."""
297
+ if not _SESSION_ID.fullmatch(seen.id):
298
+ return None
299
+ dest = _sessions()
300
+ dest.mkdir(parents=True, exist_ok=True)
301
+ with locked(dest / ".lock"):
302
+ old = _read_session(dest / f"{seen.id}.json")
303
+ new = replace(old or SessionRecord(seen.id, account_id, None, None, now),
304
+ account=account_id, cwd=seen.cwd or (old and old.cwd),
305
+ transcript=seen.transcript or (old and old.transcript), seen=now,
306
+ stranded_at=now if stranded else None if stranded is False
307
+ else old and old.stranded_at)
308
+ if seen.model:
309
+ new = replace(new, model=seen.model, model_name=seen.model_name, effort=seen.effort)
310
+ if seen.cost is not None:
311
+ new = replace(new, costs=add_cost(new.costs, now, seen.cost))
312
+ if stranded is not None:
313
+ new = replace(new, waiting_until=None)
314
+ if old and replace(old, seen=now) == new and now - old.seen < SESSION_WRITE_S:
315
+ return old
316
+ _write_session(dest, new)
317
+ _drop_old(dest, now)
318
+ return new
319
+
320
+
321
+ def update_session(session_id: str, change) -> SessionRecord | None:
322
+ """Apply `change` (the record, or None when there is none -> the new record, or None for no
323
+ change) under the sessions' lock, so a hook and `watch` cannot both act on the old record.
324
+ The record as it stands afterwards (None when there is none)."""
325
+ if not _SESSION_ID.fullmatch(session_id):
326
+ return None
327
+ dest = _sessions()
328
+ dest.mkdir(parents=True, exist_ok=True)
329
+ with locked(dest / ".lock"):
330
+ old = _read_session(dest / f"{session_id}.json")
331
+ new = change(old)
332
+ if new is None or new == old:
333
+ return old
334
+ _write_session(dest, new)
335
+ return new
336
+
337
+
338
+ def drawn_news(seen: SessionSeen, account_id: str, fresh: dict[str, Window],
339
+ now: float) -> dict[str, Window]:
340
+ """The windows in a usage hook's `fresh` that are news: changed since this session last
341
+ drew them on `account_id` (all of them on its first draw there). An idle session redraws
342
+ the last values it received, so a window it repeats says nothing, however it compares with
343
+ the snapshot (after a probe that lowered it, say). Each draw is kept in the session's
344
+ record (created when there is none), written only when it changed."""
345
+ def change(old: SessionRecord | None) -> SessionRecord:
346
+ rec = old or SessionRecord(seen.id, account_id, seen.cwd, seen.transcript, now)
347
+ drawn = {k: [w.used_pct, w.resets_at] for k, w in fresh.items()}
348
+ before = rec.drawn.get(account_id, {})
349
+ news.update({k: w for k, w in fresh.items() if before.get(k) != drawn[k]})
350
+ return replace(rec, drawn={account_id: drawn})
351
+ news: dict[str, Window] = {}
352
+ if not _SESSION_ID.fullmatch(seen.id):
353
+ return dict(fresh)
354
+ update_session(seen.id, change)
355
+ return news
356
+
357
+
358
+ def move_session(session_id: str, account_id: str) -> SessionRecord | None:
359
+ """A session resumed under its own id on `account_id`: its record names that account, is
360
+ no longer stranded or waiting; every other field (role, parent, checkpoints' requests) is
361
+ kept."""
362
+ return update_session(session_id, lambda old: old and replace(
363
+ old, account=account_id, stranded_at=None, waiting_until=None))
364
+
365
+
366
+ CHAIN_STEPS = 8 # `moved_to` links followed at most, so a damaged chain never loops
367
+
368
+
369
+ def latest(session_id: str) -> str:
370
+ """The end of the chain of recorded sessions that continue `session_id` under new ids
371
+ (`moved_to`), itself when it has not moved; stops at a cycle or after CHAIN_STEPS links."""
372
+ chain = [session_id]
373
+ while len(chain) <= CHAIN_STEPS and (r := session(chain[-1])) and r.moved_to \
374
+ and r.moved_to not in chain and session(r.moved_to):
375
+ chain.append(r.moved_to)
376
+ return chain[-1]
377
+
378
+
379
+ def link_session(old_id: str, seen: SessionSeen, account_id: str, now: float,
380
+ copy: bool = False) -> SessionRecord | None:
381
+ """`seen` continues the session `old_id` under a new id on `account_id` (a resume on another
382
+ account, or a copy). Its record takes the old one's role, parent, model, display name and
383
+ effort where it lacks them (a model `seen` names wins, as in `note_session`), the account,
384
+ `seen`'s folder and transcript, `continues=old_id`, and keeps a cost series of its own; the
385
+ old checkpoint note is copied when the new id has none. When the old session has stopped
386
+ (not `copy`), the new one takes its place: the old record keeps its account and costs, gets
387
+ `moved_to`, and is no longer stranded or waiting, and workers (their records and their
388
+ sessions' records) whose parent is the old id now name the new one. A `copy` of a session
389
+ that may still run leaves the old record and its workers as they are. None, with nothing
390
+ changed, when either id is bad, they are the same, the old record is missing or has moved
391
+ already, or the new one already continues a session."""
392
+ if old_id == seen.id or not _SESSION_ID.fullmatch(old_id) \
393
+ or not _SESSION_ID.fullmatch(seen.id):
394
+ return None
395
+ dest = _sessions()
396
+ dest.mkdir(parents=True, exist_ok=True)
397
+ with locked(dest / ".lock"):
398
+ old = _read_session(dest / f"{old_id}.json")
399
+ mine = _read_session(dest / f"{seen.id}.json")
400
+ if old is None or old.moved_to or (mine and mine.continues):
401
+ return None
402
+ new = mine or SessionRecord(seen.id, account_id, None, None, now)
403
+ model = (seen.model, seen.model_name, seen.effort) if seen.model else \
404
+ (new.model, new.model_name, new.effort) if new.model else \
405
+ (old.model, old.model_name, seen.effort or old.effort)
406
+ new = replace(new, account=account_id, cwd=seen.cwd or new.cwd or old.cwd,
407
+ transcript=seen.transcript or new.transcript, seen=now,
408
+ role=new.role or old.role, parent=new.parent or old.parent,
409
+ model=model[0], model_name=model[1], effort=model[2], continues=old_id)
410
+ _write_session(dest, new)
411
+ if not copy:
412
+ _write_session(dest, replace(old, moved_to=seen.id, stranded_at=None,
413
+ waiting_until=None))
414
+ for p in dest.glob("*.json"):
415
+ if (r := _read_session(p)) and r.parent == old_id and r.id != seen.id:
416
+ _write_session(dest, replace(r, parent=seen.id))
417
+ with locked(_workers() / ".lock"):
418
+ for w in workers(old_id):
419
+ _save_worker(replace(w, parent=seen.id))
420
+ src, dst = checkpoint_path(old_id), checkpoint_path(seen.id)
421
+ with locked(_checkpoints() / ".lock"):
422
+ if src.is_file() and not dst.exists():
423
+ fd, tmp = tempfile.mkstemp(dir=_checkpoints())
424
+ os.close(fd)
425
+ shutil.copyfile(src, tmp)
426
+ os.replace(tmp, dst)
427
+ return new
428
+
429
+
430
+ def _workers() -> Path:
431
+ return state_dir() / "workers"
432
+
433
+
434
+ def _read_worker(path: Path) -> Worker | None:
435
+ try:
436
+ d = json.loads(path.read_text())
437
+ return Worker(path.stem, str(d["parent"]), str(d["account"]), str(d["cwd"]),
438
+ float(d["started"]), _text(d.get("session")), _text(d.get("model")),
439
+ _text(d.get("effort")), _num(d.get("cost")), _num(d.get("duration")))
440
+ except (OSError, ValueError, KeyError, TypeError, AttributeError):
441
+ return None
442
+
443
+
444
+ def _save_worker(w: Worker) -> None:
445
+ _write_json(_workers(), f"{w.name}.json", {k: v for k, v in vars(w).items() if k != "name"})
446
+
447
+
448
+ def add_worker(w: Worker) -> bool:
449
+ """Record a new worker; False when a worker of that name is recorded already (its name
450
+ must be unique: it is how its session is found). Drops the records started SESSION_KEEP_S
451
+ ago or more."""
452
+ if not _SESSION_ID.fullmatch(w.name):
453
+ return False
454
+ dest = _workers()
455
+ dest.mkdir(parents=True, exist_ok=True)
456
+ with locked(dest / ".lock"):
457
+ for p in dest.glob("*.json"):
458
+ if (old := _read_worker(p)) and w.started - old.started > SESSION_KEEP_S:
459
+ with contextlib.suppress(OSError):
460
+ p.unlink()
461
+ if (dest / f"{w.name}.json").exists():
462
+ return False
463
+ _save_worker(w)
464
+ return True
465
+
466
+
467
+ def drop_worker(name: str) -> None:
468
+ """Forget a worker that never started."""
469
+ with contextlib.suppress(OSError), locked(_workers() / ".lock"):
470
+ (_workers() / f"{name}.json").unlink()
471
+
472
+
473
+ def worker(name: str) -> Worker | None:
474
+ if not _SESSION_ID.fullmatch(name):
475
+ return None
476
+ return _read_worker(_workers() / f"{name}.json")
477
+
478
+
479
+ def workers(parent: str | None = None) -> list[Worker]:
480
+ """The recorded workers (of the main session `parent`, when given), oldest first."""
481
+ found = sorted(_workers().glob("*.json")) if _workers().is_dir() else []
482
+ return sorted((w for p in found if (w := _read_worker(p))
483
+ and (parent is None or w.parent == parent)), key=lambda w: (w.started, w.name))
484
+
485
+
486
+ def finish_worker(name: str, cost: float | None, duration: float) -> bool:
487
+ """Record a worker's measured cost and duration (when it ended or went still); True when
488
+ that changed its record."""
489
+ with locked(_workers() / ".lock"):
490
+ if (w := worker(name)) is None or (w.cost, w.duration) == (cost, duration):
491
+ return False
492
+ _save_worker(replace(w, cost=cost, duration=duration))
493
+ return True
494
+
495
+
496
+ def join_worker(name: str, session_id: str) -> None:
497
+ """Note the session id a worker turned out to have."""
498
+ with locked(_workers() / ".lock"):
499
+ if (w := worker(name)) and w.session != session_id:
500
+ _save_worker(replace(w, session=session_id))
501
+
502
+
503
+ def _checkpoints() -> Path:
504
+ return state_dir() / "checkpoints"
505
+
506
+
507
+ def checkpoint_path(session_id: str) -> Path | None:
508
+ """Where a session's checkpoint note is (it may not exist); None for a bad id."""
509
+ return _checkpoints() / f"{session_id}.md" if _SESSION_ID.fullmatch(session_id) else None
510
+
511
+
512
+ def checkpointed() -> list[str]:
513
+ """The ids of the sessions that have a checkpoint note."""
514
+ return sorted(p.stem for p in _checkpoints().glob("*.md")) if _checkpoints().is_dir() else []
515
+
516
+
517
+ def append_checkpoint(session_id: str, text: str) -> Path:
518
+ """Append `text` to the session's checkpoint note, under a lock; never rewrites it."""
519
+ path = checkpoint_path(session_id)
520
+ if path is None:
521
+ raise ValueError(f"not a session id: {session_id!r}")
522
+ with locked(_checkpoints() / ".lock"), open(path, "a", encoding="utf-8") as f:
523
+ f.write(text)
524
+ return path
525
+
526
+
527
+ def _requests() -> Path:
528
+ return state_dir() / "requests"
529
+
530
+
531
+ def save_request(launcher: int, req: Request) -> None:
532
+ """Ask the launcher `launcher` (a process id) to act on its child's session: one file per
533
+ launcher, replaced atomically. The request's `pid` is the session's own process, when known,
534
+ so the launcher acts only for its own child; `manual` skips its check that the account is
535
+ out."""
536
+ _write_json(_requests(), f"{launcher}.json", vars(req))
537
+
538
+
539
+ def take_request(launcher: int) -> Request | None:
540
+ """The launcher's pending request, removed as it is read; None when there is none or it
541
+ does not read."""
542
+ path = _requests() / f"{launcher}.json"
543
+ try:
544
+ d = json.loads(path.read_text())
545
+ path.unlink()
546
+ pid = d.get("pid")
547
+ return Request(str(d["session"]), d.get("manual") is True,
548
+ pid if isinstance(pid, int) else None, _text(d.get("kind")) or "pickup",
549
+ _text(d.get("model")), _text(d.get("effort")), _text(d.get("account")))
550
+ except (OSError, ValueError, KeyError, TypeError, AttributeError):
551
+ return None
552
+
553
+
554
+ @contextlib.contextmanager
555
+ def locked(path: Path):
556
+ """Hold an exclusive lock on the file `path` (created if missing) while the block runs."""
557
+ path.parent.mkdir(parents=True, exist_ok=True)
558
+ with open(path, "a") as f:
559
+ fcntl.flock(f, fcntl.LOCK_EX)
560
+ yield
561
+
562
+
563
+ @contextlib.contextmanager
564
+ def held(lock: Path, seconds: float = 10.0, stale: float | None = None):
565
+ """Hold the lock FOLDER `lock` (made with mkdir, as some tools do for their own files) while
566
+ the block runs. Waits up to `seconds` for it; one untouched for more than `stale` seconds is
567
+ left over and is taken over. Raises OSError when it stays held."""
568
+ end = time.monotonic() + seconds
569
+ while True:
570
+ try:
571
+ os.mkdir(lock)
572
+ break
573
+ except FileExistsError:
574
+ try:
575
+ old = stale is not None and time.time() - lock.stat().st_mtime > stale
576
+ except FileNotFoundError:
577
+ continue # released meanwhile: try again
578
+ if old:
579
+ with contextlib.suppress(OSError):
580
+ os.rmdir(lock) # an empty folder; a race just means waiting on
581
+ continue
582
+ if time.monotonic() > end:
583
+ raise OSError(f"{lock} is held by someone else; try again later")
584
+ time.sleep(0.1)
585
+ try:
586
+ yield
587
+ finally:
588
+ os.rmdir(lock)
589
+
590
+
591
+ def _trust_only_file() -> Path:
592
+ return state_dir() / "trust-only.json"
593
+
594
+
595
+ def trust_only(folder: Path) -> bool:
596
+ """Whether the user answered "only" to the trust question for `folder` (canonical)."""
597
+ try:
598
+ return json.loads(_trust_only_file().read_text()).get(str(folder)) is True
599
+ except (OSError, ValueError, AttributeError):
600
+ return False
601
+
602
+
603
+ def remember_trust_only(folder: Path) -> None:
604
+ """Remember "only" for `folder`: one small JSON map, rewritten atomically under a lock."""
605
+ path = _trust_only_file()
606
+ with locked(path.with_name(path.name + ".lock")):
607
+ try:
608
+ d = json.loads(path.read_text())
609
+ d = d if isinstance(d, dict) else {}
610
+ except (OSError, ValueError):
611
+ d = {}
612
+ _write_json(state_dir(), path.name, {**d, str(folder): True})
613
+
614
+
615
+ def free_name(path: Path) -> Path:
616
+ """`path`, or the same name with -1, -2... added when that already exists."""
617
+ found, n = path, 1
618
+ while os.path.lexists(found):
619
+ found, n = path.with_name(f"{path.name}-{n}"), n + 1
620
+ return found
621
+
622
+
623
+ def write_with_backup(path: Path, text: str, backups: Path | None = None) -> Path | None:
624
+ """Replace a file atomically, first copying any existing one beside it with a timestamp (or
625
+ into the folder `backups`), then read it back. A symlink is written through to its target,
626
+ never replaced by a regular file. Returns the backup's path, or None when there was nothing
627
+ to back up."""
628
+ if path.is_symlink():
629
+ path = path.resolve()
630
+ path.parent.mkdir(parents=True, exist_ok=True)
631
+ backup = None
632
+ if path.exists():
633
+ if backups is None:
634
+ stamp = time.strftime("%Y%m%d-%H%M%S")
635
+ backup = free_name(path.with_name(f"{path.name}.bak-fairshare-{stamp}"))
636
+ else:
637
+ backups.mkdir(parents=True, exist_ok=True)
638
+ backup = free_name(backups / path.name)
639
+ shutil.copy2(path, backup)
640
+ fd, tmp = tempfile.mkstemp(dir=path.parent)
641
+ with os.fdopen(fd, "w", encoding="utf-8") as f:
642
+ f.write(text)
643
+ if backup:
644
+ shutil.copymode(backup, tmp)
645
+ os.replace(tmp, path)
646
+ if path.read_text(encoding="utf-8") != text:
647
+ raise OSError(f"{path}: what was read back differs from what was written")
648
+ return backup