1# Continuous Operation Runbook
2 
3This runbook explains how to run the researcher harness as a daemon on macOS so it can advance the research-to-skill loop for days without manual intervention.
4 
5## What Runs
6 
7| Job | Frequency | Purpose |
8| --- | --- | --- |
9| `loop_step.py` | every 10 minutes | pull from inbox, advance one active run by one state, park anything that needs human or judge review |
10| `loop_discover.py` | twice daily (05:00 and 17:00 local) | append new candidate sources from configured feeds into the inbox |
11| `loop_daily.py` | once daily (06:30 local) | run repo validation, activation cases, benchmarks, write a dated snapshot, flag volatile claims due for review |
12| `loop_status.py` | piggy-backs on every `loop_step` and `loop_daily` | refresh the dashboard and parked review surface |
13 
14All schedules and budgets live in `researcher/orchestration/config.json`. Default budgets:
15 
16- max active runs: 3
17- max runs per day: 6
18- max parked: 12
19- max failures per day: 5
20- max inbox size: 200
21 
22When any budget is exceeded the loop stops doing destructive work and continues only with bookkeeping until the human reviews.
23 
24## Install
25 
26```bash
27researcher/orchestration/launchd/install.sh
28```
29 
30The script:
31 
321. Substitutes the repository path into the launchd plists.
332. Writes them under `~/Library/LaunchAgents/`.
343. Bootstraps them under the current user agent domain.
354. Enables the labels so they survive logout/login.
36 
37Logs land in `researcher/reports/logs/`:
38 
39- `loop_step.log`, `loop_discover.log`, `loop_daily.log`, `loop_status.log`
40- `launchd-loop-step.out` and `.err` for raw launchd output
41 
42## Uninstall
43 
44```bash
45researcher/orchestration/launchd/uninstall.sh
46```
47 
48## Manual Operation
49 
50You can run the loop scripts directly without launchd:
51 
52```bash
53python3 researcher/scripts/loop_discover.py            # pull new sources into inbox
54python3 researcher/scripts/loop_step.py --allow-fetch  # advance one step
55python3 researcher/scripts/loop_daily.py               # benchmarks + snapshot
56python3 researcher/scripts/loop_status.py              # refresh dashboard
57```
58 
59`--allow-fetch` enables HTTP GET retrieval through Python's stdlib `urllib`. Without it the loop parks runs that need source retrieval and waits for a human.
60 
61## Human Review Surface
62 
63Read these files when checking on the loop:
64 
65- `researcher/reports/status.md` - high-level dashboard.
66- `researcher/reports/parked-review.md` - runs waiting for a reviewer.
67- `researcher/reports/snapshots/<date>.md` - daily snapshot.
68- `researcher/reports/benchmark-history.jsonl` - append-only benchmark trend.
69- `researcher/queue/inbox.jsonl` - candidate sources awaiting initialization.
70- `researcher/queue/quarantine.jsonl` - sources removed from rotation.
71 
72Parked runs require one of these actions:
73 
74| Reason | Action |
75| --- | --- |
76| `needs source retrieval` | retrieve manually and run `research_loop.py retrieve --run-dir <run> --file <evidence>` |
77| `needs evaluation` | complete the source evaluation JSON and run `research_loop.py evaluate --run-dir <run>` |
78| `needs human or model action from state proposed` | finish the proposal and run `research_loop.py novelty --run-dir <run>` |
79| `needs merge approval` | review the PR notes; merge only after explicit approval |
80 
81## Safety
82 
83- The loop never invokes LLMs or paid APIs.
84- Source retrieval uses stdlib `urllib` with a 30-second timeout and a 1.5MB cap.
85- Sources that fail twice are quarantined.
86- The mechanism registry can only be updated through `research_loop.py promote-mechanisms` with a recorded reviewer; the loop does not edit it.
87- Push and merge are always human-controlled.
88 
89## Daily Rhythm
90 
91A reasonable cadence for a human running this:
92 
931. Morning: read the latest snapshot and parked review.
942. Pick up to three parked runs and either advance, reject, or abandon them.
953. Approve any mechanism promotions whose runs are publish-ready.
964. Leave the loop running for the next day.
97