pi-sleep-agent 0.8.19 → 0.8.21

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.
package/README.md CHANGED
@@ -35,6 +35,13 @@ Sleep adds a reviewable memory cycle to nine selectable coding-agent targets. It
35
35
  procedures, environment warnings) instead of moving them out of reach with the file, so
36
36
  what leaves T0 is what a pass could have read. The count is printed instead of being
37
37
  inferred from the proposal count.
38
+ - **A pass that reads its own report.** `doctor` findings are not decoration: `sleep` and
39
+ `nightly` score them, and a problem that gets worse while it waits (a backlog past the read
40
+ window, an unconfirmed memory still being served as context) waives the `--min-interval` check
41
+ so the pass runs now instead of on the clock. The record floor always holds, the reason in the
42
+ report names the interval as waived and the score that waived it, and `--min-urgency 0` (or
43
+ `--no-doctor-gate`) restores the flat policy exactly. Scoring reads the hygiene report only;
44
+ it makes no model call, so the unattended path spends nothing new.
38
45
  - **Review before permanence.** New memories stay provisional until you promote or refuse them.
39
46
  - **Nightly dream cycle.** Mine repeated preferences, consolidate recent observations, and measure memory effects while you are away.
40
47
  - **Measured replay.** Run the same task with memory off and on before deciding whether a memory helps. Each completed pass leaves a one-line quality summary (`helps / hurts / ties`) in `status` and in the nightly report, so the question stays answerable between passes; a pass whose two arms ran the same prompt says it measured nothing instead of reporting zeros.
@@ -156,7 +163,7 @@ entries, and backs up JSON/TOML files before changing them. It is one Python
156
163
  script and works on macOS, Linux, and Windows; per-platform scheduling is chosen
157
164
  automatically:
158
165
 
159
- - **macOS** - a LaunchAgent (`~/Library/LaunchAgents/com.aydinnyunus.sleep-nightly.plist`).
166
+ - **macOS** - a LaunchAgent (`~/Library/LaunchAgents/com.aydinnyunus.sleep-nightly.plist`), registered with `launchctl bootstrap` and read back with `launchctl print`, so an install that launchd did not take says so instead of printing "loaded".
160
167
  - **Linux** - a cron job (`crontab -l`, kept inside owned `# BEGIN/END aydinnyunus-sleep-nightly` markers).
161
168
  - **Windows** - a Task Scheduler task via `schtasks /create /tn aydinnyunus-sleep-nightly`.
162
169
 
@@ -362,6 +369,7 @@ Run the two dream components separately when you want more control:
362
369
  | `./sleep.py status -v` | ... and the last measured memory quality (`3 helps / 1 hurts / 4 ties from 8 samples`, or "no replay measurement has run yet") |
363
370
  | `./sleep.py mine --dry-run` | Find preferences repeated across sessions |
364
371
  | `./sleep.py nightly --dry-run` | Preview the unattended nightly workflow |
372
+ | `./sleep.py sleep --min-urgency <points>` | Score the hygiene findings and let them waive `--min-interval` (default 2: a growing backlog or a stale candidate clears it, a dangling link does not). `--min-urgency 0` or `--no-doctor-gate` keeps the flat policy, and the record floor (`--min-records`) is never waived |
365
373
  | `./sleep.py doctor` | Find duplicate or overlapping memory records, flag contradicting candidates (same subject, one side carries a correction marker) and print the `supersede <older> <newer>` command to run, flag provisional candidates unrediscovered past their kind's threshold (4 weeks for a fact, 13 for a preference, 8 for a procedure, 52 for a warning; kind and threshold appear in the finding), flag records no session was ever served past their kind's unused threshold (8 / 26 / 12 / 52), flag supersede pointers that name a record no longer in the store, report a T0 buffer larger
366
374
  than the 120-record consolidation window (with the count left outside it), and report records
367
375
  parked in quarantine awaiting a human (report only: it never supersedes, drops, merges or un-parks anything itself) |
package/docs/EVIDENCE.md CHANGED
@@ -583,3 +583,118 @@ preference promotable, agent fact and warning promotable, speculative source sti
583
583
  per-session `buffer-exceeds-consolidation-window` finding
584
584
  (`test_many_small_sessions_are_not_one_large_buffer`: six 20-record sessions are six complete
585
585
  passes, not one 120-record buffer, and the doctor says nothing).
586
+
587
+
588
+ ## 2026-11-03: the hygiene report feeds the gate instead of sitting beside it
589
+
590
+ Section 6 of `docs/TMP-sleep-framework-gaps.md` named the gap: "zamanlama sabit eşikler ...
591
+ `doctor`'ın bulguları rapor, tetikleyici değil". That was exact. `doctor` computed a backlog past
592
+ the read window, stale candidates that no longer earn their place, and an armed-and-never-fired
593
+ schedule; `sleep_gate` then asked only "3 records and 6 hours since the last pass". The report and
594
+ the decision lived in the same process and never spoke.
595
+
596
+ `consolidate.URGENCY_WEIGHTS` puts a value on each finding a doctor can emit - a growing backlog 3,
597
+ a stale candidate or an unserved record 2, a dangling link or a quarantine 1 - and
598
+ `consolidate.urgency(findings)` sums them into a score with a reason that names the largest
599
+ contributor and the counts. Everything not in the table weighs 0, so a finding added later cannot
600
+ open a gate by accident; that is deliberate, not an oversight.
601
+
602
+ `sleep_gate` takes `urgency_score` and `min_urgency`. A score at or above the bar waives the
603
+ interval check ONLY: the record floor is never waived, because "enough happened to be worth
604
+ reading" is a different question from "a problem is waiting". Both defaults reproduce the old
605
+ behaviour byte for byte (`urgency_score=0` and `min_urgency=0` each do it independently), which is
606
+ what makes this safe to land under a hook or a cron entry that passes neither.
607
+
608
+ Measured on a clean `SLEEP_HOME`, 130 buffered records and one 200-day-old preference, with
609
+ `last_sleep` set to now so the interval blocks a second pass:
610
+
611
+ - `sleep --dry-run` -> `would-run`, `urgency 7`, reason `ran early: urgency 7 >= 2 | last sleep 0.0h
612
+ ago, minimum interval 6h waived`
613
+ - `sleep --dry-run --no-doctor-gate` -> `skipped`, `urgency 0`, reason `last sleep 0.0h ago, minimum
614
+ interval 6h`
615
+ - `nightly --dry-run --no-mine` -> the doctor report and the sleep gate carry the SAME three issues
616
+ (`stale-candidate-unrediscovered`, `unused-candidate-never-served`,
617
+ `buffer-exceeds-consolidation-window`); the gate is handed the report the night already computed
618
+ rather than reading candidate frontmatter a second time.
619
+
620
+ Cost: `burst` is unchanged. Scoring calls `store.doctor()` with no needle, which reads candidate
621
+ frontmatter and the T0 counts and makes no model call; only `doctor --contradictions` spends, and
622
+ that is not on this path. `nightly` reuses its own report, so the unattended night reads once.
623
+
624
+ Deliberately not done, so the edges are not mistaken for coverage:
625
+
626
+ - No decay, no deletion, no demotion. The score decides WHEN a pass runs, never what a record is
627
+ worth. Dropping records is still a human act, and `prune` is still the explicit clear-out.
628
+ - The record floor is not waivable. A buffer with two records and a month of backlog waits.
629
+ - `replay` keeps its own clock (`--replay-interval`): what replay measures is whether a memory
630
+ helps, and a hygiene finding says nothing about that.
631
+ - One finding still weighs more than a person's time than it should: `quarantine-awaiting-review`
632
+ is scored 1 because a night cannot resolve a quarantine, so a quarantine alone will not wake a
633
+ pass. A person who wants it to can pass `--min-urgency 1`.
634
+
635
+ Pinned by `tests/test_core.py::T` (`test_urgency_weights_come_from_the_table_and_name_it`,
636
+ `test_every_weight_the_doctor_can_emit_is_a_known_row`,
637
+ `test_urgency_waives_the_interval_but_never_the_record_floor`,
638
+ `test_run_sleep_reports_why_it_ran_early`).
639
+
640
+
641
+ ## 2026-11-05: a scheduled pass that was never scheduled
642
+
643
+ The nightly pass existed, was installed, and had not run for two nights. The plist was
644
+ present (`~/Library/LaunchAgents/com.aydinnyunus.sleep-nightly.plist`, mtime 2026-11-01
645
+ 21:44, `StartCalendarInterval` 03:41, `RunAtLoad` true) and `launchctl list` did not
646
+ carry its label at all. `nightly.log` held exactly two records, `2026-11-01T03:41:05`
647
+ and `2026-11-01T21:44:57`; nothing on 11-02, 11-03, 11-04 or 11-05.
648
+
649
+ Measured (before the change):
650
+
651
+ $ launchctl list | grep aydinnyunus
652
+ - 0 com.aydinnyunus.claude-curator
653
+ $ launchctl print gui/502/com.aydinnyunus.sleep-nightly
654
+ Could not find service ... in domain for user gui: 502
655
+ $ launchctl print-disabled gui/502 | grep sleep
656
+ (nothing)
657
+
658
+ The job was not disabled, it was never registered. `tools/install.py` registered it with
659
+ `launchctl load <path>`, which exits 0 in a case where launchd holds no job: the install
660
+ printed "loaded" and the schedule was inert. A silent install failure is the worst shape
661
+ here, because the only symptom is a night with no output, and a night with no
662
+ consolidation looks exactly like a night where nothing needed consolidating.
663
+
664
+ The loader now uses `launchctl bootstrap gui/<uid> <path>` and then reads the job back
665
+ with `launchctl print`; `enable` is called after `bootstrap` so a label a previous run
666
+ disabled cannot stay disabled across an install; `bootout` runs first because `bootstrap`
667
+ is not idempotent (EEXIST over a loaded label). The uninstall side now `bootout`s by
668
+ label as well as `unload`ing by path.
669
+
670
+ Measured (after the change, on this machine, `load_launchd()` called directly):
671
+
672
+ load_launchd before: False
673
+ load_launchd -> True
674
+ load_launchd after: True
675
+
676
+ $ launchctl print gui/502/com.aydinnyunus.sleep-nightly
677
+ path = /Users/yunus.aydin/Library/LaunchAgents/com.aydinnyunus.sleep-nightly.plist
678
+ state = not running
679
+ runs = 1
680
+ last exit code = 0
681
+
682
+ `runs = 1` and `last exit code = 0` are the `RunAtLoad` fire, and it wrote a record into
683
+ `nightly.log` while this was being measured:
684
+
685
+ "ts": "2026-11-05T23:59:24+0300"
686
+ "sleep": {"action": "skipped", "buffer_records": 1,
687
+ "gate": {"min_interval_hours": 0.0, "min_records": 2, "min_urgency": 2.0,
688
+ "urgency": 1,
689
+ "urgency_detail": "quarantine-awaiting-review (+1; quarantine-awaiting-review x1)"},
690
+ "reason": "buffer has 1 record(s), needs 2"}
691
+
692
+ Two things land in that line: the schedule runs now, and the 0.8.20 gate carries its
693
+ reason into the unattended report (`urgency 1` is below `min_urgency 2`, and the record
694
+ floor refuses regardless).
695
+
696
+ Pinned by `tests/test_cli.py::InstallUninstall`
697
+ (`test_mac_scheduler_bootstraps_the_agent_and_reads_it_back`,
698
+ `test_mac_scheduler_reports_a_bootstrap_that_registers_nothing`). The fakes hold jobs in
699
+ a state file, so the read-back is a real second call and not a restatement of the first,
700
+ and the second test fails if "loaded" is ever printed on the strength of an exit code.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-sleep-agent",
3
- "version": "0.8.19",
3
+ "version": "0.8.21",
4
4
  "description": "A reviewable sleep and dream cycle for Pi agent memory.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/sleepkit/cli.py CHANGED
@@ -46,7 +46,8 @@ def cmd_sleep(a) -> int:
46
46
  rep = consolidate.run_sleep(session=a.session, model=a.model, budget_usd=a.budget,
47
47
  min_records=a.min_records,
48
48
  min_interval_hours=a.min_interval,
49
- force=a.force, dry_run=a.dry_run)
49
+ force=a.force, dry_run=a.dry_run,
50
+ min_urgency=0 if a.no_doctor_gate else a.min_urgency)
50
51
  _p(json.dumps(rep, indent=2, sort_keys=True, default=str))
51
52
  if rep.get("action") == "ran":
52
53
  return 0 if rep.get("ok") is not False else 3
@@ -457,12 +458,18 @@ def cmd_nightly(a) -> int:
457
458
  # The hygiene report lands in the night regardless of the gates: it is
458
459
  # read-only, so the worst an unattended pass can do is surface a stale
459
460
  # value (e.g. a changed deployment URL) for a person to act on later.
460
- rep["doctor"] = {"issues": store.doctor(needle=a.stale)}
461
+ issues = store.doctor(needle=a.stale)
462
+ rep["doctor"] = {"issues": issues}
463
+ # The hygiene report is handed to the gate rather than recomputed: same read, one
464
+ # night, and it is what lets a finding move the pass off the flat interval. With
465
+ # --no-doctor-gate the gate gets the old policy and the report is unaffected.
461
466
  rep["sleep"] = consolidate.run_sleep(session=a.session, model=a.model,
462
467
  budget_usd=a.budget,
463
468
  min_records=a.min_records,
464
469
  min_interval_hours=a.min_interval,
465
- force=a.force, dry_run=a.dry_run)
470
+ force=a.force, dry_run=a.dry_run,
471
+ findings=issues,
472
+ min_urgency=0 if a.no_doctor_gate else a.min_urgency)
466
473
  rep["replay"] = replay_mod.nightly(tasks_path=a.replay_tasks, model=a.model,
467
474
  budget=a.replay_budget,
468
475
  limit=a.replay_limit,
@@ -672,6 +679,12 @@ def main(argv=None) -> int:
672
679
  sl.add_argument("--min-records", type=int, default=3, dest="min_records")
673
680
  sl.add_argument("--min-interval", type=float, default=6.0, dest="min_interval",
674
681
  help="hours between sleeps")
682
+ sl.add_argument("--min-urgency", type=float, default=consolidate.URGENCY_DEFAULT,
683
+ dest="min_urgency",
684
+ help="doctor findings worth at least this many points skip the "
685
+ "interval check (0 = flat policy, no hygiene scan)")
686
+ sl.add_argument("--no-doctor-gate", action="store_true", dest="no_doctor_gate",
687
+ help="do not score the hygiene report; the interval is never waived")
675
688
  sl.add_argument("--force", action="store_true")
676
689
  sl.add_argument("--dry-run", action="store_true")
677
690
  sl.set_defaults(fn=cmd_sleep)
@@ -748,6 +761,12 @@ def main(argv=None) -> int:
748
761
  nt.add_argument("--min-records", type=int, default=3, dest="min_records")
749
762
  nt.add_argument("--min-interval", type=float, default=6.0, dest="min_interval",
750
763
  help="hours between consolidations")
764
+ nt.add_argument("--min-urgency", type=float, default=consolidate.URGENCY_DEFAULT,
765
+ dest="min_urgency",
766
+ help="hygiene findings worth at least this many points skip the "
767
+ "interval check (0 = flat policy)")
768
+ nt.add_argument("--no-doctor-gate", action="store_true", dest="no_doctor_gate",
769
+ help="score the hygiene report but never waive the interval")
751
770
  nt.add_argument("--force", action="store_true")
752
771
  nt.add_argument("--dry-run", action="store_true")
753
772
  nt.add_argument("--replay-interval", type=float, default=168.0, dest="replay_interval",
@@ -446,28 +446,137 @@ def hours_since(ts):
446
446
  return (datetime.now(dt.tzinfo) - dt).total_seconds() / 3600.0
447
447
 
448
448
 
449
- def sleep_gate(records: int, min_records: int, min_interval_hours: float) -> tuple[bool, str]:
449
+ # What a doctor finding is worth as a reason to run NOW. The thresholds above answer
450
+ # "is it time"; these answer "is it needed", and until now nothing consumed them: the
451
+ # pass ran on a flat 6h/3-record policy while `doctor` printed a backlog, stale
452
+ # candidates and an armed-but-never-fired schedule into a report nobody wired to a
453
+ # decision. Each row is (weight, label) and the label travels with the number so a
454
+ # report can never name a weight that did not produce it.
455
+ #
456
+ # buffer-exceeds-consolidation-window 3 the problem gets worse every hour it waits
457
+ # stale-candidate-unrediscovered 2 an unconfirmed memory is still being
458
+ # injected as context; leaving it is not
459
+ # neutral, it is a wrong thing kept alive
460
+ # unused-candidate-never-served 2 a record no session ever saw is a memory
461
+ # that has not paid for itself either way
462
+ # broken-supersede-link 1 a real defect, but it does not grow
463
+ # quarantine-awaiting-review 1 needs a person, not a pass; scoring it low
464
+ # keeps a night from running for something a
465
+ # night cannot fix
466
+ # contradicting-candidates 1 adjudication is a human act; the pass may
467
+ # surface it, but it cannot settle it
468
+ # near-duplicate-candidates 1
469
+ # candidate-duplicates-memory 1
470
+ # stale-value-in-memory 1
471
+ #
472
+ # Everything else (duplicate-heading-in-file and any future issue) weighs 0 on
473
+ # purpose: a new finding must be given a weight deliberately, and an unknown one must
474
+ # never be able to open a gate by accident.
475
+ URGENCY_WEIGHTS = {
476
+ "buffer-exceeds-consolidation-window": (3, "the backlog grows until a pass runs"),
477
+ "stale-candidate-unrediscovered": (2, "unconfirmed memory is still served as context"),
478
+ "unused-candidate-never-served": (2, "a record no session was ever served"),
479
+ "broken-supersede-link": (1, "a link dangles but does not grow"),
480
+ "quarantine-awaiting-review": (1, "needs a person, not a pass"),
481
+ "contradicting-candidates": (1, "the pass can surface it, only a person can settle it"),
482
+ "near-duplicate-candidates": (1, "hygiene, cheap to leave for the next pass"),
483
+ "candidate-duplicates-memory": (1, "hygiene, cheap to leave for the next pass"),
484
+ "stale-value-in-memory": (1, "a stale fact, but the record still holds its subject"),
485
+ }
486
+
487
+ # The default bar a finding must clear to waive the interval. 2 means "a problem that
488
+ # grows, or a memory that is being served while unconfirmed"; 0 turns the whole
489
+ # mechanism off and restores the flat policy exactly.
490
+ URGENCY_DEFAULT = 2.0
491
+
492
+
493
+ def urgency(findings: list) -> tuple[int, str]:
494
+ """(score, reason) for a doctor report. Read-only, no model call.
495
+
496
+ Deliberately a SUM of at most a few points rather than a max: three stale
497
+ candidates and a growing backlog is a different night from one dangling link, and
498
+ the number is reported so the difference is inspectable instead of implied. The
499
+ reason names the largest single contributor, because that is the one a person
500
+ reading the log would act on first.
501
+ """
502
+ total = 0
503
+ best_w = 0
504
+ best_issue = ""
505
+ counts: dict = {}
506
+ for f in findings or []:
507
+ issue = str((f or {}).get("issue", ""))
508
+ w, _label = URGENCY_WEIGHTS.get(issue, (0, ""))
509
+ if not w:
510
+ continue
511
+ total += w
512
+ counts[issue] = counts.get(issue, 0) + 1
513
+ # Ties go to the first row in table order, which is also weight order, so the
514
+ # reason is stable across runs and does not depend on dict iteration order.
515
+ if w > best_w:
516
+ best_w, best_issue = w, issue
517
+ if not total:
518
+ return 0, ""
519
+ parts = ", ".join("%s x%d" % (k, v) for k, v in sorted(counts.items()))
520
+ return total, "%s (+%d; %s)" % (best_issue, total, parts)
521
+
522
+
523
+ def sleep_gate(records: int, min_records: int, min_interval_hours: float,
524
+ urgency_score: int = 0, min_urgency: float = URGENCY_DEFAULT) -> tuple[bool, str]:
525
+ """Is it time? The record floor always holds; urgency can waive only the interval.
526
+
527
+ `urgency_score <= 0` and `min_urgency <= 0` both reproduce the historical behaviour
528
+ byte for byte, which is what makes this safe to add under callers that do not pass
529
+ either (a hook, a hand-typed `sleep`, an older script). A waive is reported as
530
+ such, because "policy satisfied" and "ran early because 4 stale candidates were
531
+ still being injected" are different facts about the night and a log has to tell
532
+ them apart.
533
+ """
450
534
  state = paths.read_state()
451
535
  last = state.get("last_sleep")
452
536
  if records < min_records:
453
537
  return False, f"buffer has {records} record(s), needs {min_records}"
454
538
  elapsed = hours_since(last)
455
539
  if elapsed is not None and elapsed < min_interval_hours:
456
- return False, f"last sleep {elapsed:.1f}h ago, minimum interval {min_interval_hours:g}h"
540
+ if urgency_score > 0 and min_urgency > 0 and urgency_score >= min_urgency:
541
+ return True, ("ran early: urgency %d >= %g | last sleep %.1fh ago, "
542
+ "minimum interval %gh waived"
543
+ % (urgency_score, min_urgency, elapsed, min_interval_hours))
544
+ return False, f"last sleep {elapsed:.1f}h ago, minimum interval {min_interval_hours:g}h"
457
545
  return True, "policy satisfied"
458
546
 
459
547
 
460
548
  def run_sleep(session=None, model=None, budget_usd=1.0, min_records=3,
461
- min_interval_hours=6.0, force=False, dry_run=False):
549
+ min_interval_hours=6.0, force=False, dry_run=False,
550
+ findings=None, min_urgency=URGENCY_DEFAULT):
462
551
  """The entry point a hook or a cron job calls. Cheap when there is nothing
463
- to consolidate: one stat and one JSON read, no model call."""
552
+ to consolidate: one stat, one JSON read and a read-only hygiene scan, no model call.
553
+
554
+ `findings` is a caller-supplied `store.doctor()` report, and passing one is the
555
+ point of the argument: `nightly` already computes it for its own report, and
556
+ reading candidate frontmatter twice in one night would be waste dressed as
557
+ thoroughness. When it is None and `min_urgency` is on, the scan runs here, which
558
+ costs file reads and no API call (only `doctor --contradictions` spends, and that
559
+ is not on this path).
560
+ """
464
561
  records = store.buffer_counts()["records"]
465
- ok, reason = sleep_gate(records, min_records, min_interval_hours)
562
+ score = 0
563
+ detail = ""
564
+ if min_urgency and min_urgency > 0:
565
+ if findings is None:
566
+ findings = store.doctor()
567
+ score, detail = urgency(findings)
568
+ ok, reason = sleep_gate(records, min_records, min_interval_hours,
569
+ urgency_score=score, min_urgency=min_urgency)
570
+ gate = {"min_records": min_records, "min_interval_hours": min_interval_hours,
571
+ "min_urgency": min_urgency, "urgency": score}
572
+ if detail:
573
+ gate["urgency_detail"] = detail
466
574
  if not ok and not force:
467
- return {"action": "skipped", "reason": reason, "buffer_records": records}
575
+ return {"action": "skipped", "reason": reason, "buffer_records": records,
576
+ "gate": gate}
468
577
  if dry_run:
469
578
  return {"action": "would-run", "reason": reason if ok else reason + " (forced)",
470
- "buffer_records": records}
579
+ "buffer_records": records, "gate": gate}
471
580
  if not acquire_lock():
472
581
  return {"action": "locked", "reason": "another consolidation is running",
473
582
  "buffer_records": records}
@@ -478,7 +587,7 @@ def run_sleep(session=None, model=None, budget_usd=1.0, min_records=3,
478
587
  state["sleep_count"] = int(state.get("sleep_count", 0)) + 1
479
588
  state["last_sleep_result"] = {k: result.get(k) for k in
480
589
  ("proposals", "accepted", "refused", "llm_exit",
481
- "buffer_records", "outside_window")}
590
+ "buffer_records", "outside_window", "gate")}
482
591
  paths.write_state(state)
483
592
  # Synaptic pruning only after a consolidation that actually produced
484
593
  # proposals. Pruning a buffer the model never read would silently discard