entropy-machines 0.1.1

package/bin/drain

@@ -0,0 +1,507 @@
+#!/bin/sh
+# Arm, disarm, inspect, install, or hand-fire the unattended drainer.
+#
+#   bin/drain on          # arm it — the next scheduled fire does work
+#   bin/drain off         # disarm — fires still happen and exit immediately
+#   bin/drain status      # armed? scheduled? last fire? last quota wall? eligible?
+#   bin/drain now         # run one fire in the foreground, right now
+#   bin/drain at HH:MM    # one detached one-shot fire, today or tomorrow
+#   bin/drain cancel      # cancel a pending one-shot
+#   bin/drain install     # install the scheduled job (launchd on macOS,
+#                         #  a systemd --user timer on Linux)
+#
+# WHY A FLAG FILE RATHER THAN LOADING/UNLOADING THE SCHEDULER.
+#
+# Unloading a scheduled job is a stateful operation on the job definition that
+# also has to survive reboots and login cycles, and getting it wrong leaves the
+# job either permanently dead or permanently running with no obvious tell. A
+# flag file is a boolean the runner reads at the top of every fire: `off` takes
+# effect on the next fire with nothing to reload, `on` needs no privileges, and
+# `status` can answer honestly by reading one path. The scheduled job stays
+# installed either way.
+set -e
+
+. "$(dirname "$0")/../lib/roots.sh"
+ENTROPY_MACHINES_HOME=$(entropy_machines_home "$0")
+entropy_machines_require_root drain
+os=$(uname)
+
+# ---- config -----------------------------------------------------------------
+# cfg <dotted.path> <default>
+# One value out of config.json at the project root. A missing file, a missing
+# key, or a value that is not a plain scalar all fall back to <default> — this
+# harness has to keep running before a project has written every key, per
+# docs/CONFIG.md rule 2 (a working default, or a refusal naming the key; the
+# refusal is this script's job for the keys that truly have none, e.g. an
+# unsupported scheduler below).
+cfg() {
+  python3 - "$ENTROPY_MACHINES_HOME/config.json" "$1" "$2" <<'PY'
+import json, sys
+path, key, default = sys.argv[1], sys.argv[2], sys.argv[3]
+try:
+    with open(path) as f:
+        data = json.load(f)
+except Exception:
+    print(default); sys.exit(0)
+cur = data
+# TOLERATE A LEADING DOT. Every call site in this file and in bin/drain writes
+# the key as '.unattended.x' (a jq habit), which split('.') turns into a first
+# segment of '' that matches no dict key — so this helper silently returned its
+# DEFAULT for every lookup, and no unattended setting in config.json had any
+# effect. Fixed here rather than at a dozen call sites so both spellings work.
+for part in key.lstrip('.').split('.'):
+    if isinstance(cur, dict) and part in cur:
+        cur = cur[part]
+    else:
+        print(default); sys.exit(0)
+print(default if cur is None else (cur if isinstance(cur, str) else json.dumps(cur)))
+PY
+}
+
+state_default=$(cfg '.unattended.stateHome' '~/.entropy')
+case "$state_default" in
+  "~"*) state_default="$HOME${state_default#\~}" ;;
+esac
+state="${ENTROPY_DRAIN_HOME:-$state_default}"
+label=$(cfg '.unattended.label' 'com.entropy.drain')
+flag="$state/armed"
+log="$state/last-run.json"
+
+mkdir -p "$state"
+
+# ---- which scheduler ---------------------------------------------------------
+# Sets $scheduler, $scheduler_source, $have_launchd, $have_systemd. Called by
+# both `status` and `install` so the two cannot disagree about what this machine
+# can do — the previous split (status hardcoded "Darwin or unsupported", install
+# hardcoded a Darwin refusal) is exactly the shape that let `status` claim a
+# platform had no scheduler while an installer for it existed.
+#
+# AVAILABLE means the client binary is reachable, not that the platform sounds
+# right: launchd needs macOS AND launchctl; systemd needs systemctl (present on
+# Linux, and absent on a Linux running some other init, which is the case a
+# uname check gets wrong).
+#
+# An explicit unattended.scheduler always wins, including when it names one this
+# machine cannot run — a wrong value must be a refusal that says so, never a
+# silent fallback to the other scheduler. Only an ABSENT key is detected.
+drain_scheduler_probe() {
+  have_launchd=no
+  have_systemd=no
+  # `if`, not `[ test ] && VAR=value` — see the note in `install` below: as a
+  # bare statement under `set -e` that form EXITS the script when the test is
+  # false, which is how a probe would take the whole command down on Linux.
+  if [ "$os" = Darwin ] && command -v launchctl >/dev/null 2>&1; then
+    have_launchd=yes
+  fi
+  if command -v systemctl >/dev/null 2>&1; then
+    have_systemd=yes
+  fi
+  scheduler=$(cfg '.unattended.scheduler' '')
+  if [ -n "$scheduler" ]; then
+    scheduler_source=config
+    return 0
+  fi
+  scheduler_source=detected
+  if [ "$have_launchd" = yes ]; then
+    scheduler=launchd
+  elif [ "$have_systemd" = yes ]; then
+    scheduler=systemd
+  else
+    scheduler=none
+  fi
+  return 0
+}
+
+# What the probe looked for, printed verbatim by every refusal so the message
+# names the check rather than the conclusion.
+drain_scheduler_looked_for() {
+  echo "  It looked for:" >&2
+  echo "    launchd — macOS (uname reports '$os') and 'launchctl' on PATH: $have_launchd" >&2
+  echo "    systemd — 'systemctl' on PATH: $have_systemd" >&2
+}
+
+case "${1:-status}" in
+  on)
+    date -u +%Y-%m-%dT%H:%M:%SZ > "$flag"
+    echo "drain: ARMED (since $(cat "$flag"))"
+    echo "  the next scheduled fire will pick up work; 'bin/drain off' stops it."
+    ;;
+
+  off)
+    rm -f "$flag"
+    echo "drain: DISARMED"
+    echo "  fires still happen on schedule and exit immediately. Nothing to unload."
+    ;;
+
+  status)
+    # Two independent switches, and confusing them is the likely support
+    # question: the job can be installed but disarmed (fires, does nothing), or
+    # armed but never installed (nothing ever fires). Report both.
+    scheduled=no
+    drain_scheduler_probe
+    case "$scheduler" in
+      launchd)
+        if [ "$have_launchd" != yes ]; then
+          scheduled=unavailable
+        elif launchctl list 2>/dev/null | grep -q "$label"; then
+          scheduled=yes
+        fi
+        ;;
+      systemd)
+        if [ "$have_systemd" != yes ]; then
+          scheduled=unavailable
+        elif systemctl --user is-active --quiet "$label.timer" 2>/dev/null; then
+          # The TIMER is the thing that is loaded and waiting; the .service it
+          # fires is inactive almost all the time and would read as "no".
+          scheduled=yes
+        fi
+        ;;
+      none)
+        # Nothing this installer implements exists on this machine, so there is
+        # no job of ours to look for — say that rather than pointing at an
+        # install that refuses.
+        scheduled=unsupported
+        ;;
+      *)
+        # config.json names a scheduler this installer does not implement. A
+        # different message: the machine may well be fine, the config is not.
+        scheduled=unknown
+        ;;
+    esac
+    if [ "$scheduled" = yes ]; then
+      echo "scheduled:  yes (hourly, at :07, via $scheduler)"
+    elif [ "$scheduled" = unknown ]; then
+      echo "scheduled:  n/a — config.json's unattended.scheduler is '$scheduler',"
+      echo "            which 'bin/drain install' does not implement (launchd, systemd)"
+    elif [ "$scheduled" = unavailable ]; then
+      # The scheduler was NAMED (only config.json can name one that is not
+      # here — detection never picks an unusable one), and it is not usable on
+      # this machine. Say which one and which check failed, not "unsupported":
+      # the other scheduler may well be sitting right there.
+      echo "scheduled:  n/a — unattended.scheduler is '$scheduler' ($scheduler_source),"
+      echo "            not usable here (launchctl: $have_launchd, systemctl: $have_systemd, uname: $os);"
+      echo "            'bin/drain install' will refuse and say the same"
+    elif [ "$scheduled" = unsupported ]; then
+      echo "scheduled:  n/a — no scheduler 'bin/drain install' can use is available"
+      echo "            here (launchctl: $have_launchd, systemctl: $have_systemd, uname: $os);"
+      echo "            fire bin/drain-run.sh from your own cron entry instead"
+    else
+      echo "scheduled:  no — run 'bin/drain install'"
+    fi
+    if [ -f "$state/once.pid" ] && kill -0 "$(cat "$state/once.pid")" 2>/dev/null; then
+      echo "one-shot:   $(cat "$state/once.at" 2>/dev/null) (pid $(cat "$state/once.pid"))"
+    else
+      echo "one-shot:   none — 'bin/drain at HH:MM' to set one"
+    fi
+    if [ -f "$flag" ]; then
+      echo "armed:      yes (since $(cat "$flag"))"
+    else
+      echo "armed:      no — run 'bin/drain on'"
+    fi
+    if [ -f "$log" ]; then
+      # Heredoc + env var rather than `python3 -c '...'`: the inline form needs
+      # quotes nested three deep (sh, python, f-string) and the first version
+      # of this line printed its own source back four times.
+      DRAIN_LOG="$log" python3 <<'PY'
+import json, os
+try:
+    d = json.load(open(os.environ["DRAIN_LOG"]))
+    print(f'last fire:  {d.get("finishedAt", "?")} — {d.get("outcome", "?")}'
+          f' ({d.get("detail", "")})')
+except Exception as exc:
+    print(f"last fire:  unreadable ({exc})")
+PY
+    else
+      echo "last fire:  never"
+    fi
+    # The quota probe lives in bin/drain-run.sh (--probe-quota) so there is
+    # exactly one implementation; see that file for what it assumes.
+    lookback=$(cfg '.unattended.agent.quotaProbe.lookbackSeconds' '3600')
+    l=$("$ENTROPY_MACHINES_HOME/bin/drain-run.sh" --probe-quota 2>/dev/null || true)
+    if [ -n "$l" ]; then
+      echo "quota wall: $l"
+    else
+      echo "quota wall: none seen in the last $((lookback / 60))m (or no probe configured)"
+    fi
+    # What it would actually take, so `status` answers "is there anything to
+    # do" and not merely "is the switch up".
+    if [ -x "$ENTROPY_MACHINES_HOME/bin/tracker" ]; then
+      n=$("$ENTROPY_MACHINES_HOME/bin/tracker" ready 2>/dev/null | grep -c . || true)
+      echo "eligible:   ${n:-0} issue(s) an unattended run may take"
+    fi
+    ;;
+
+  now)
+    echo "drain: firing once in the foreground (ignores the armed flag)"
+    exec "$ENTROPY_MACHINES_HOME/bin/drain-run.sh" --foreground
+    ;;
+
+  at)
+    # One fire at a time you name — the answer to "can I just read a reset time
+    # off the agent's own usage panel and resume then". You can, and a rolling
+    # window means that reading is only true for today, which is exactly what a
+    # ONE-SHOT is for. The hourly probe chases a moving window; this hits a
+    # boundary you already know. They do not conflict and neither needs the
+    # other.
+    when="$2"
+    case "$when" in
+      [0-9][0-9]:[0-9][0-9]) ;;
+      *) echo "usage: bin/drain at HH:MM   (24-hour, local)" >&2; exit 2 ;;
+    esac
+    hh=${when%:*}; mm=${when#*:}
+    # Strip a leading zero before arithmetic — 08 and 09 are invalid octal.
+    hh=$((10#$hh)); mm=$((10#$mm))
+    if [ "$hh" -gt 23 ] || [ "$mm" -gt 59 ]; then
+      echo "bin/drain at: $when is not a real time" >&2; exit 2
+    fi
+    # A DETACHED SLEEP, not a scheduled job. On macOS specifically, a repo
+    # under a TCC-protected folder (see `install` below) cannot be reached by
+    # a LaunchAgent at all, but a process spawned from your terminal inherits
+    # the terminal's TCC grant and reads the repo fine — so this is the form
+    # that works everywhere, no permission changes, no scheduler install.
+    #
+    # The trade: it does not survive a reboot, and if the machine sleeps
+    # through the target the timer resumes on wake and fires late rather than
+    # on time. For "resume at the reset I just read off my own usage panel",
+    # that is the right shape anyway — you are naming a moment tonight, not a
+    # standing schedule.
+    #
+    # Portable date math: BSD date (macOS) and GNU date (Linux) parse and
+    # format dates with incompatible flags (`-j -f` vs `-d`), and neither can
+    # be assumed present in the other's form. Routing through python3's
+    # stdlib `datetime` sidesteps both dialects entirely — it behaves
+    # identically on every platform this harness targets, unlike `date` itself.
+    now_s=$(date +%s)
+    tgt_s=$(python3 - "$hh" "$mm" <<'PY'
+import datetime, sys
+hh, mm = int(sys.argv[1]), int(sys.argv[2])
+tgt = datetime.datetime.now().replace(hour=hh, minute=mm, second=0, microsecond=0)
+print(int(tgt.timestamp()))
+PY
+)
+    [ -z "$tgt_s" ] && { echo "bin/drain at: could not compute a target time" >&2; exit 2; }
+    if [ "$tgt_s" -le "$now_s" ]; then
+      tgt_s=$((tgt_s + 86400))   # already past today → mean tomorrow
+    fi
+    wait_s=$((tgt_s - now_s))
+    tgt_str=$(python3 - "$tgt_s" <<'PY'
+import datetime, sys
+print(datetime.datetime.fromtimestamp(int(sys.argv[1])).strftime('%Y-%m-%d %H:%M'))
+PY
+)
+    # Replace any pending one-shot rather than stacking two fires.
+    if [ -f "$state/once.pid" ] && kill -0 "$(cat "$state/once.pid")" 2>/dev/null; then
+      kill "$(cat "$state/once.pid")" 2>/dev/null || true
+    fi
+    nohup sh -c "sleep $wait_s; exec '$ENTROPY_MACHINES_HOME/bin/drain-run.sh' --foreground" \
+      > "$state/once.log" 2>&1 &
+    echo $! > "$state/once.pid"
+    printf '%s\n' "$tgt_str" > "$state/once.at"
+    echo "drain: one fire at $tgt_str — in $((wait_s / 60)) min (pid $(cat "$state/once.pid"))"
+    echo "  runs whether or not 'drain on' is set; log: $state/once.log"
+    echo "  cancel with: bin/drain cancel"
+    echo "  NOTE: a detached timer, so it does not survive a reboot."
+    ;;
+
+  cancel)
+    if [ -f "$state/once.pid" ] && kill -0 "$(cat "$state/once.pid")" 2>/dev/null; then
+      kill "$(cat "$state/once.pid")" 2>/dev/null || true
+      echo "drain: cancelled the one-shot that was set for $(cat "$state/once.at" 2>/dev/null)"
+    else
+      echo "drain: no one-shot pending"
+    fi
+    rm -f "$state/once.pid" "$state/once.at"
+    if [ "$os" = "Darwin" ] && command -v launchctl >/dev/null 2>&1; then
+      launchctl bootout "gui/$(id -u)/$label.once" 2>/dev/null || true
+      rm -f "$HOME/Library/LaunchAgents/$label.once.plist"
+    fi
+    ;;
+
+  install)
+    # ONLY THE INSTALLER IS PLATFORM-SPECIFIC. Everything else in this script —
+    # on, off, status, now, at, cancel — is plain POSIX sh and runs anywhere, so
+    # the platform check belongs here and nowhere higher up.
+    #
+    # Two schedulers, and nothing else. An installer that reports success and
+    # leaves a broken job behind is worse than no installer, because every
+    # surface (`status`, `launchctl list`, `systemctl --user is-active`) then
+    # agrees it is armed — so anything we cannot write a unit for is a refusal
+    # that installs nothing, and says which check failed.
+    drain_scheduler_probe
+
+    runner="$ENTROPY_MACHINES_HOME/bin/drain-run.sh"
+
+    if [ "$scheduler" = none ]; then
+      echo "bin/drain install: refusing — no scheduler this installer supports is" >&2
+      echo "  available on this machine, and config.json's unattended.scheduler" >&2
+      echo "  does not name one." >&2
+      drain_scheduler_looked_for
+      echo "  Nothing was installed. Drive the fires yourself instead: put" >&2
+      echo "    $runner" >&2
+      echo "  on your own cron entry or timer. 'bin/drain on/off' is still the" >&2
+      echo "  arm/disarm switch whatever triggers the fire, and 'bin/drain now'" >&2
+      echo "  / 'bin/drain at HH:MM' need no scheduler at all." >&2
+      exit 3
+    fi
+
+    case "$scheduler" in
+      launchd)
+        # The platform gate that used to sit above the whole command, now
+        # scoped to the path it is actually about. Reached when this is the
+        # DETECTED scheduler (in which case it passes by construction) or when
+        # config.json asks for launchd on a machine that has no launchctl.
+        if [ "$have_launchd" != yes ]; then
+          echo "bin/drain install: refusing — unattended.scheduler is 'launchd'" >&2
+          echo "  ($scheduler_source), and launchd is not usable on this machine." >&2
+          drain_scheduler_looked_for
+          if [ "$have_systemd" = yes ]; then
+            echo "  systemd IS available here: set unattended.scheduler to 'systemd'" >&2
+            echo "  in config.json, or remove the key and let this detect it." >&2
+          fi
+          echo "  Nothing was installed. 'bin/drain now' / 'bin/drain at HH:MM'" >&2
+          echo "  need no scheduler at all." >&2
+          exit 3
+        fi
+        # TCC (Transparency, Consent and Control) — a macOS-only OS security
+        # subsystem — refuses a LaunchAgent filesystem access to ~/Desktop,
+        # ~/Documents and ~/Downloads. Installing a job that is denied before
+        # its first line is worse than installing none, because `launchctl
+        # list` shows it loaded and everything looks armed. Check the actual
+        # repo location(s) and say so. This entire check is a macOS concept
+        # and does not apply on Linux.
+        #
+        # Both locations are checked: launchd has to reach ENTROPY_MACHINES_HOME to
+        # exec the runner script at all, and drain-run.sh then reads/writes
+        # inside ENTROPY_MACHINES_ROOT (git, config.json, .entropy/) to do the work.
+        # They are usually the same tree now, but not the same DIRECTORY when
+        # the harness is vendored in a subdirectory, so either one sitting
+        # under a protected folder denies the job — checked separately so the
+        # message names the one that is actually the problem.
+        tcc_blocked=""
+        for tcc_dir in "$ENTROPY_MACHINES_HOME" "$ENTROPY_MACHINES_ROOT"; do
+          case "$tcc_dir" in
+            "$HOME"/Desktop/*|"$HOME"/Documents/*|"$HOME"/Downloads/*)
+              echo "bin/drain install: refusing — this is in a TCC-protected folder:" >&2
+              echo "  $tcc_dir" >&2
+              tcc_blocked=1
+              ;;
+          esac
+        done
+        if [ -n "$tcc_blocked" ]; then
+          echo "  A LaunchAgent is denied here before it runs a line. Three ways forward:" >&2
+          echo "    1. bin/drain at HH:MM      — a detached timer, works today," >&2
+          echo "                                 no permissions, no reboot survival" >&2
+          echo "    2. move it out of that folder (e.g. ~/code/<project>)" >&2
+          echo "    3. System Settings -> Privacy & Security -> Full Disk Access," >&2
+          echo "       add /bin/sh — broad, since it grants every shell script" >&2
+          echo "  Override once you have done 2 or 3: ENTROPY_DRAIN_FORCE=1" >&2
+          # `if`, not `[ ... ] && exit`. Under `set -e` a bare `[ test ] &&
+          # cmd` used as a STATEMENT exits the whole script when the test is
+          # FALSE — so with the override set, this line silently killed the
+          # install it was meant to permit. Also `${...:-}`: the variable is
+          # normally unset.
+          if [ -z "${ENTROPY_DRAIN_FORCE:-}" ]; then
+            exit 3
+          fi
+          echo "  ENTROPY_DRAIN_FORCE set — installing anyway." >&2
+        fi
+        # A scheduler unit fires with no useful cwd. That used to be a gap:
+        # nothing carried the project root in, so an installed job only worked
+        # when the harness sat AT the project root. With one root it resolves
+        # itself — bin/drain-run.sh cd's into the harness directory, which is
+        # inside the repo, and git answers from there. No placeholder needed.
+        plist="$HOME/Library/LaunchAgents/$label.plist"
+        mkdir -p "$HOME/Library/LaunchAgents"
+        sed "s|__RUNNER__|$runner|g; s|__STATE__|$state|g; s|__LABEL__|$label|g" \
+          "$ENTROPY_MACHINES_HOME/lib/entropy-drain.plist.in" > "$plist"
+        launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+        launchctl bootstrap "gui/$(id -u)" "$plist"
+        echo "drain: launchd job installed and loaded (hourly probe)"
+        echo "  it is INERT until you run 'bin/drain on'."
+        echo "  to remove: launchctl bootout gui/$(id -u)/$label && rm $plist"
+        echo
+        echo "  One step left, and it needs sudo so it is yours to run — without it"
+        echo "  the job cannot fire while the machine is asleep:"
+        echo "    sudo pmset repeat wakeorpoweron MTWRFSU 02:00:00"
+        ;;
+
+      systemd)
+        if [ "$have_systemd" != yes ]; then
+          echo "bin/drain install: refusing — unattended.scheduler is 'systemd'" >&2
+          echo "  ($scheduler_source), and there is no 'systemctl' on PATH here." >&2
+          drain_scheduler_looked_for
+          if [ "$have_launchd" = yes ]; then
+            echo "  launchd IS available here: set unattended.scheduler to 'launchd'" >&2
+            echo "  in config.json, or remove the key and let this detect it." >&2
+          fi
+          echo "  Nothing was installed. 'bin/drain now' / 'bin/drain at HH:MM'" >&2
+          echo "  need no scheduler at all." >&2
+          exit 3
+        fi
+        # systemctl EXISTS is not the same as a user manager we can talk to: in
+        # an ssh session or a container with no per-user systemd instance,
+        # `--user` fails on a missing DBUS_SESSION_BUS_ADDRESS/XDG_RUNTIME_DIR.
+        # Ask before writing anything, so the failure mode is a refusal rather
+        # than two unit files on disk that no daemon-reload ever picked up.
+        if ! systemctl --user show-environment >/dev/null 2>&1; then
+          echo "bin/drain install: refusing — 'systemctl --user' cannot reach a user" >&2
+          echo "  manager for $(id -un) (no session bus; XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-unset})." >&2
+          echo "  This is usually an ssh or container session with no logind seat." >&2
+          echo "  Nothing was installed. Either run this from a full login session," >&2
+          echo "  or enable a lingering one first:" >&2
+          echo "    sudo loginctl enable-linger $(id -un)" >&2
+          exit 3
+        fi
+        # No TCC equivalent to check: the macOS branch above refuses a repo
+        # under ~/Desktop, ~/Documents or ~/Downloads because a LaunchAgent is
+        # denied those paths by the OS before it runs a line. Linux has no such
+        # per-directory grant for a user unit — a user timer reads whatever the
+        # user can read — so there is nothing here to refuse for.
+        #
+        # A user unit, so no sudo and no system-wide state: everything lands
+        # under the operator's own XDG config dir and is undone by deleting two
+        # files. Same substitution as the plist, from templates beside it.
+        unit_dir="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
+        service="$unit_dir/$label.service"
+        timer="$unit_dir/$label.timer"
+        mkdir -p "$unit_dir"
+        sed "s|__RUNNER__|$runner|g; s|__STATE__|$state|g; s|__LABEL__|$label|g" \
+          "$ENTROPY_MACHINES_HOME/lib/entropy-drain.service.in" > "$service"
+        sed "s|__RUNNER__|$runner|g; s|__STATE__|$state|g; s|__LABEL__|$label|g" \
+          "$ENTROPY_MACHINES_HOME/lib/entropy-drain.timer.in" > "$timer"
+        systemctl --user daemon-reload
+        # --now starts the timer as well as enabling it, so the first fire does
+        # not wait for the next login. The TIMER is enabled, never the service:
+        # enabling a oneshot service would run it at boot instead of on
+        # schedule. It is still inert until `bin/drain on`.
+        systemctl --user enable --now "$label.timer"
+        echo "drain: systemd user timer installed and started (hourly probe)"
+        echo "  it is INERT until you run 'bin/drain on'."
+        echo "  to check:  systemctl --user list-timers $label.timer"
+        echo "  to remove: systemctl --user disable --now $label.timer &&"
+        echo "             rm $timer $service && systemctl --user daemon-reload"
+        echo
+        echo "  One step left, and it needs sudo so it is yours to run — without it"
+        echo "  the timer is torn down when your last session logs out, and never"
+        echo "  fires on a machine you are not sitting at:"
+        echo "    sudo loginctl enable-linger $(id -un)"
+        ;;
+
+      *)
+        echo "bin/drain install: unknown scheduler '$scheduler' (unattended.scheduler" >&2
+        echo "  in config.json) — the schedulers this installer supports are" >&2
+        echo "  'launchd' (macOS) and 'systemd' (a systemd --user timer). Remove the" >&2
+        echo "  key to have it detect one. On anything else, call bin/drain-run.sh" >&2
+        echo "  from a timer you write yourself (cron, a CI schedule)." >&2
+        exit 2
+        ;;
+    esac
+    ;;
+
+  *)
+    echo "usage: bin/drain [status|now|at HH:MM|cancel|on|off|install]" >&2
+    echo "  at HH:MM   one fire at a time you name" >&2
+    echo "  on/off     the hourly probe, for windows you have not read" >&2
+    exit 2
+    ;;
+esac

package/bin/drain-pick.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Choose the issues one unattended fire will take. Prints ids, space-separated.
+
+    bin/drain-pick.py [<repo-root>]
+
+Its own file rather than a heredoc inside drain-run.sh, for two reasons. A
+heredoc piped from `tracker ready` would have the pipe and the heredoc both
+claiming stdin, which is a real way to have python read the TRACKER OUTPUT as
+its own source and die on a syntax error. And a selection rule with a cap in
+it is worth testing directly, which a heredoc cannot be.
+
+THE RULE. A cap phrased as separate small/medium/large limits ("N small, M
+medium, P large only") does not compose — it has nothing to say about a fire
+that wants two smalls and one medium. Recasting the caps as unit costs that
+share one budget makes mixing fall out for free instead of needing a new rule
+per combination.
+
+Costs and the budget are project config (`unattended.sizeCosts`,
+`unattended.budget` in config.json) with defaults chosen so a few small caps
+land on the same number:
+
+    S = 3    M = 4    L = 6    budget = 12
+
+    4 x S = 12      3 x M = 12      2 x L = 12
+
+Every pure-class fire is therefore identical to what flat per-size caps of
+4/3/2 would allow, and mixing now falls out of the same number: L + M + S is
+13, over budget, so it takes L + M; L + S + S is 12, so it takes all three.
+
+Selection walks the ranked list — the order `bin/tracker ready` printed it
+in — and takes anything that still fits, skipping what does not and
+continuing. Skipping rather than stopping matters: one large issue at rank
+three should not strand a fire with 6 unspent points when there are smaller
+items below it. Rank is never reordered — a cheaper issue is only ever
+reached after every dearer one above it was considered.
+
+ENTROPY_DRAIN_BUDGET overrides the configured budget for a bigger or smaller
+fire without touching the per-size costs.
+
+Eligibility is exactly what `bin/tracker ready` prints (docs/TRACKER-ADAPTER.md)
+and nothing else — so an issue cannot be picked while blocked, held, or gated
+on an open decision. There is no separate "autonomous" flag in the adapter
+contract: an issue a human decided an unattended run should not touch is
+`held`, via `bin/tracker set <id> heldWhy=...` (see bin/drain-prompt.md), and
+`ready` already excludes it.
+"""
+import json
+import os
+import subprocess
+import sys
+
+DEFAULT_COST = {"S": 3, "M": 4, "L": 6}
+DEFAULT_BUDGET = 12
+
+
+def load_cost_model(root):
+    """(costs, budget) out of config.json's `unattended` block.
+
+    Not read through lib/config.py — that loader does not define these two
+    keys yet (see its DEFAULTS dict), and this script only needs two scalars,
+    not the full merge/validate pipeline. A missing file, a missing key, or a
+    malformed value all fall back to the defaults above rather than raising —
+    same posture as bin/drain's and bin/drain-run.sh's own `cfg()` helper.
+    """
+    try:
+        with open(os.path.join(root, "config.json"), encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        data = {}
+    unattended = data.get("unattended") or {}
+    costs = unattended.get("sizeCosts")
+    if not isinstance(costs, dict) or not costs:
+        costs = DEFAULT_COST
+    budget = unattended.get("budget")
+    if not isinstance(budget, (int, float)):
+        budget = DEFAULT_BUDGET
+    return costs, budget
+
+
+def parse(text):
+    """[(id, effort)] in listed order — `bin/tracker ready`'s JSONL, one
+    issue record per line (docs/TRACKER-ADAPTER.md).
+
+    A line that fails to parse, or parses but carries no "id", is skipped
+    rather than aborting the whole pick — one malformed record from a
+    `command` backend should not zero out an otherwise-eligible fire.
+    `effort` is optional in the adapter contract; a record without one is
+    handled by the caller's fail-closed default, same as an unrecognised
+    value.
+    """
+    out = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(rec, dict):
+            continue
+        iid = rec.get("id")
+        if not iid:
+            continue
+        out.append((iid, rec.get("effort")))
+    return out
+
+
+def pick(rows, costs, budget):
+    """Walk the ranked list, take whatever still fits, return the ids.
+
+    An unrecognised or missing effort costs the most a fire can hold.
+    Fail-closed: a typo'd or newly-invented size (or an issue nobody sized at
+    all) must not become the cheapest thing on the list and let an
+    unattended run take an unbounded amount of it.
+    """
+    left = budget
+    taken = []
+    fallback = max(costs.values()) if costs else budget
+    for iid, effort in rows:
+        c = costs.get(effort, fallback)
+        if c <= left:
+            taken.append(iid)
+            left -= c
+    return taken
+
+
+def _tracker_path():
+    """bin/tracker, resolved from THIS FILE rather than from the project root.
+
+    It used to be os.path.join(root, "bin", "tracker"), where root is the
+    PROJECT. That is only the same directory when the harness happens to sit
+    at the repo root; in the vendored-in-a-subdirectory layout it resolves to
+    <project>/bin/tracker, which does not exist, and every unattended pick
+    died with ENOENT. This file is a sibling of tracker inside the harness, so
+    its own location is the answer and is right in either layout.
+    """
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)), "tracker")
+
+
+def main():
+    root = sys.argv[1] if len(sys.argv) > 1 else \
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    costs, budget = load_cost_model(root)
+    override = os.environ.get("ENTROPY_DRAIN_BUDGET")
+    if override:
+        try:
+            budget = float(override)
+        except ValueError:
+            print(f"drain-pick: ENTROPY_DRAIN_BUDGET={override!r} is not a "
+                  f"number, ignoring", file=sys.stderr)
+    try:
+        r = subprocess.run(
+            [_tracker_path(), "ready"],
+            capture_output=True, text=True, timeout=60)
+    except (OSError, subprocess.SubprocessError) as exc:
+        print(f"drain-pick: cannot reach the tracker: {exc}", file=sys.stderr)
+        return 1
+    if r.returncode != 0:
+        print(f"drain-pick: tracker exited {r.returncode}: {r.stderr.strip()}",
+              file=sys.stderr)
+        return 1
+    print(" ".join(pick(parse(r.stdout), costs, budget)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())