polyrob 0.5.0__py3-none-any.whl

cron/schedule.py

@@ -0,0 +1,194 @@
+"""Schedule parsing + next-run computation for the cron subsystem (roadmap P5).
+
+Pure and tz-naive (local wall-clock) so it is deterministic and unit-testable —
+every entry point takes the reference time explicitly. Supported spec formats:
+
+- duration interval ............ ``30m``, ``2h``, ``1d``, ``45s`` (also ``every 15m``)
+- one-shot ISO timestamp ....... ``2026-06-07T09:30:00``
+- 5-field cron ................. ``*/15 * * * *`` (min hour dom mon dow; dow 0/7=Sun)
+- every-phrase ................. ``every day 14:30``, ``every monday 09:00``
+
+Anything else raises :class:`ScheduleError`.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import List, Optional
+
+_UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+_WEEKDAYS = {
+    "monday": 1, "tuesday": 2, "wednesday": 3, "thursday": 4,
+    "friday": 5, "saturday": 6, "sunday": 0,
+}
+_DURATION_RE = re.compile(r"^(\d+)\s*([smhd])$")
+_HHMM_RE = re.compile(r"^(\d{1,2}):(\d{2})$")
+_MAX_LOOKAHEAD_MINUTES = 366 * 24 * 60  # ~1 year safety bound
+
+
+class ScheduleError(ValueError):
+    """Raised when a schedule spec cannot be parsed."""
+
+
+@dataclass(frozen=True)
+class Schedule:
+    kind: str            # "interval" | "cron" | "once"
+    one_shot: bool
+    interval_seconds: Optional[int] = None
+    once_at: Optional[datetime] = None
+    cron_fields: Optional[tuple] = None  # (minutes, hours, doms, months, dows) sets
+    # POSIX day-of-month / day-of-week are OR'd when BOTH are restricted (not "*").
+    dom_restricted: bool = False
+    dow_restricted: bool = False
+
+    def next_run_after(self, after: datetime) -> Optional[datetime]:
+        """Return the next fire time strictly after ``after`` (None if none)."""
+        if self.kind == "interval":
+            return after + timedelta(seconds=self.interval_seconds)
+        if self.kind == "once":
+            return self.once_at if self.once_at > after else None
+        if self.kind == "cron":
+            return self._next_cron(after)
+        raise ScheduleError(f"unknown schedule kind: {self.kind}")
+
+    def _next_cron(self, after: datetime) -> Optional[datetime]:
+        minutes, hours, doms, months, dows = self.cron_fields
+        dt = after.replace(second=0, microsecond=0) + timedelta(minutes=1)
+        for _ in range(_MAX_LOOKAHEAD_MINUTES):
+            cron_dow = dt.isoweekday() % 7  # Mon..Sun(7)->1..0 ; Sunday == 0
+            # POSIX rule: when BOTH day-of-month and day-of-week are restricted, the
+            # job runs when EITHER matches (union); otherwise AND the restricted one.
+            if self.dom_restricted and self.dow_restricted:
+                day_match = (dt.day in doms) or (cron_dow in dows)
+            elif self.dom_restricted:
+                day_match = dt.day in doms
+            elif self.dow_restricted:
+                day_match = cron_dow in dows
+            else:
+                day_match = True
+            if (dt.minute in minutes and dt.hour in hours
+                    and dt.month in months and day_match):
+                return dt
+            dt += timedelta(minutes=1)
+        return None
+
+
+def parse_schedule(spec: str) -> Schedule:
+    if not spec or not spec.strip():
+        raise ScheduleError("empty schedule spec")
+    raw = spec.strip()
+    low = raw.lower()
+
+    # every-phrase
+    if low.startswith("every "):
+        return _parse_every(low[len("every "):].strip())
+
+    # duration interval
+    m = _DURATION_RE.match(low)
+    if m:
+        seconds = int(m.group(1)) * _UNIT_SECONDS[m.group(2)]
+        if seconds <= 0:
+            raise ScheduleError(f"non-positive interval: {spec}")
+        return Schedule(kind="interval", one_shot=False, interval_seconds=seconds)
+
+    # 5-field cron
+    if len(raw.split()) == 5:
+        return _parse_cron(raw)
+
+    # ISO timestamp (one-shot)
+    try:
+        once_at = datetime.fromisoformat(raw)
+    except ValueError:
+        raise ScheduleError(f"unrecognized schedule spec: {spec!r}")
+    # Normalize a tz-aware input to naive LOCAL time so it compares against the
+    # scheduler's naive datetime.now() — a tz-aware once_at otherwise raised
+    # "can't compare offset-naive and offset-aware datetimes" out of next_run_after.
+    if once_at.tzinfo is not None:
+        once_at = once_at.astimezone().replace(tzinfo=None)
+    return Schedule(kind="once", one_shot=True, once_at=once_at)
+
+
+def _parse_every(rest: str) -> Schedule:
+    # "every 15m" -> interval
+    m = _DURATION_RE.match(rest)
+    if m:
+        seconds = int(m.group(1)) * _UNIT_SECONDS[m.group(2)]
+        if seconds <= 0:
+            # A zero/negative interval makes every scheduler tick see the job as due,
+            # re-running it forever (runaway cost). Reject like the bare-duration path.
+            raise ScheduleError(f"interval must be positive: every {rest!r}")
+        return Schedule(kind="interval", one_shot=False, interval_seconds=seconds)
+
+    parts = rest.split()
+    if len(parts) != 2:
+        raise ScheduleError(f"unrecognized 'every' phrase: every {rest!r}")
+    when, time_str = parts
+    hm = _HHMM_RE.match(time_str)
+    if not hm:
+        raise ScheduleError(f"bad time in 'every' phrase: {time_str!r}")
+    hour, minute = int(hm.group(1)), int(hm.group(2))
+    if not (0 <= hour < 24 and 0 <= minute < 60):
+        raise ScheduleError(f"time out of range: {time_str!r}")
+
+    if when == "day":
+        dows = set(range(7))
+        dow_restricted = False  # every day -> DOW not restricted
+    elif when in _WEEKDAYS:
+        dows = {_WEEKDAYS[when]}
+        dow_restricted = True   # every <weekday> -> DOW restricted, honor the set
+    else:
+        raise ScheduleError(f"unknown day in 'every' phrase: {when!r}")
+    fields = ({minute}, {hour}, set(range(1, 32)), set(range(1, 13)), dows)
+    return Schedule(kind="cron", one_shot=False, cron_fields=fields,
+                    dom_restricted=False, dow_restricted=dow_restricted)
+
+
+def _parse_cron(raw: str) -> Schedule:
+    fields = raw.split()
+    ranges = [(0, 59), (0, 23), (1, 31), (1, 12), (0, 7)]
+    try:
+        minutes = _expand(fields[0], *ranges[0])
+        hours = _expand(fields[1], *ranges[1])
+        doms = _expand(fields[2], *ranges[2])
+        months = _expand(fields[3], *ranges[3])
+        dows = _expand(fields[4], *ranges[4])
+    except ScheduleError:
+        raise
+    except Exception as e:
+        raise ScheduleError(f"bad cron expression {raw!r}: {e}")
+    if 7 in dows:  # cron allows 7 for Sunday; normalize to 0
+        dows = (dows - {7}) | {0}
+    # A field is "restricted" when it is not a bare/stepped wildcard (Vixie rule:
+    # first char != '*'), which selects POSIX OR semantics when both are restricted.
+    dom_restricted = not fields[2].strip().startswith("*")
+    dow_restricted = not fields[4].strip().startswith("*")
+    return Schedule(kind="cron", one_shot=False,
+                    cron_fields=(minutes, hours, doms, months, dows),
+                    dom_restricted=dom_restricted, dow_restricted=dow_restricted)
+
+
+def _expand(field: str, lo: int, hi: int) -> set:
+    """Expand one cron field into a set of ints. Supports * , - and */n."""
+    result: set = set()
+    for part in field.split(","):
+        step = 1
+        body = part
+        if "/" in part:
+            body, step_s = part.split("/", 1)
+            step = int(step_s)
+            if step <= 0:
+                raise ScheduleError(f"bad step in {field!r}")
+        if body == "*":
+            start, end = lo, hi
+        elif "-" in body:
+            a, b = body.split("-", 1)
+            start, end = int(a), int(b)
+        else:
+            start = end = int(body)
+        if start < lo or end > hi or start > end:
+            raise ScheduleError(f"cron field out of range: {part!r} (allowed {lo}-{hi})")
+        result.update(range(start, end + 1, step))
+    if not result:
+        raise ScheduleError(f"empty cron field: {field!r}")
+    return result

cron/scheduler.py

@@ -0,0 +1,201 @@
+"""Cron tick scheduler (roadmap P5).
+
+Finds due jobs, runs each through an injected async ``runner`` under a hard
+duration cap, then reschedules (recurring) or completes (one-shot). A file-based
+tick lock makes a tick safe to fire from multiple processes (``UVICORN_WORKERS>1``)
+without double-running jobs. The runner is injected so the scheduler is fully
+unit-testable without the agent stack; the production runner (see
+``cron.runner``) reuses the agent core with the per-run cap.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Awaitable, Callable, List, Optional
+
+from cron.jobs import CronJob, CronJobStore
+from cron.schedule import parse_schedule, ScheduleError
+
+logger = logging.getLogger(__name__)
+
+# A held lock older than this (seconds) is considered stale and stolen — guards
+# against a crashed worker leaving the tick permanently locked.
+_LOCK_STALE_SECONDS = 600
+
+Runner = Callable[[CronJob], Awaitable[bool]]
+
+
+class TickLock:
+    """Exclusive cross-process lock via O_CREAT|O_EXCL, with stale-steal."""
+
+    def __init__(self, lock_path: str):
+        self.lock_path = lock_path
+        self._fd: Optional[int] = None
+
+    def acquire(self) -> bool:
+        parent = os.path.dirname(self.lock_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        try:
+            self._fd = os.open(self.lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            if self._is_stale():
+                try:
+                    os.unlink(self.lock_path)
+                except OSError:
+                    return False
+                return self.acquire()
+            return False
+        os.write(self._fd, str(os.getpid()).encode())
+        return True
+
+    def _is_stale(self) -> bool:
+        try:
+            age = time.time() - os.path.getmtime(self.lock_path)
+        except OSError:
+            return False
+        return age > _LOCK_STALE_SECONDS
+
+    def refresh(self) -> None:
+        """Bump the lock-file mtime so a long-but-LIVE tick is not seen as stale.
+
+        Without this the mtime is fixed at O_CREAT time; a tick that legitimately
+        runs longer than _LOCK_STALE_SECONDS (several due jobs each capped at
+        ~180s) would be judged stale and stolen by another worker, whose
+        reclaim_stale_running() then resets the live worker's rows and double-runs.
+        """
+        try:
+            os.utime(self.lock_path, None)
+        except OSError:
+            pass
+
+    def _owner_pid(self) -> Optional[int]:
+        try:
+            with open(self.lock_path, "rb") as f:
+                return int((f.read().strip() or b"0").decode() or "0")
+        except (OSError, ValueError):
+            return None
+
+    def release(self) -> None:
+        if self._fd is not None:
+            try:
+                os.close(self._fd)
+            finally:
+                self._fd = None
+        # Ownership-checked unlink: if a heartbeat gap let our lock be stolen and
+        # another worker recreated it, do NOT delete THEIR lock.
+        try:
+            if self._owner_pid() == os.getpid():
+                os.unlink(self.lock_path)
+        except OSError:
+            pass
+
+
+@dataclass
+class TickResult:
+    ran: List[str] = field(default_factory=list)
+    failed: List[str] = field(default_factory=list)
+    skipped_locked: bool = False
+    skipped_busy: bool = False
+
+
+class CronScheduler:
+    def __init__(self, store: CronJobStore, runner: Runner, *, lock_path: str):
+        self.store = store
+        self.runner = runner
+        self.lock_path = lock_path
+
+    async def tick(self, now: Optional[datetime] = None) -> TickResult:
+        from core.interactive_gate import is_interactive_busy
+        if is_interactive_busy():
+            # human mid-turn in the REPL; defer cron execution (jobs stay due for
+            # the next idle tick, sharing the CWD workspace safely).
+            return TickResult(skipped_busy=True)
+        now = now or datetime.now()
+        lock = TickLock(self.lock_path)
+        if not lock.acquire():
+            logger.debug("cron tick skipped: lock held")
+            return TickResult(skipped_locked=True)
+        try:
+            # C2: also hold the cross-process workspace lock so a cron run in this
+            # process doesn't mutate the shared CWD workspace while a `rob` REPL in
+            # another process is mid-turn. Non-blocking (timeout=0). Acquire is
+            # fail-open (any lock error -> defer the tick); errors from the run
+            # itself propagate normally (not masked by the lock handling).
+            from core.interactive_gate import workspace_turn_lock
+            ws = workspace_turn_lock(timeout=0)
+            try:
+                ws.__enter__()
+            except Exception:
+                logger.debug("cron tick skipped: workspace lock unavailable/held")
+                return TickResult(skipped_busy=True)
+            # Heartbeat the tick lock so a legitimately long tick (>_LOCK_STALE_SECONDS)
+            # is never seen as stale + stolen by another worker (which would then
+            # reclaim + double-run this tick's in-flight jobs).
+            hb = asyncio.create_task(self._lock_heartbeat(lock))
+            try:
+                return await self._run_due(now)
+            finally:
+                hb.cancel()
+                try:
+                    ws.__exit__(None, None, None)
+                except Exception:
+                    pass
+        finally:
+            lock.release()
+
+    async def _lock_heartbeat(self, lock: "TickLock") -> None:
+        interval = max(30.0, _LOCK_STALE_SECONDS / 3.0)
+        try:
+            while True:
+                await asyncio.sleep(interval)
+                lock.refresh()
+        except asyncio.CancelledError:
+            pass
+
+    async def _run_due(self, now: datetime) -> TickResult:
+        result = TickResult()
+        # Reclaim crash-orphaned 'running' jobs here — we hold the TickLock, so any
+        # 'running' row is genuinely stale (a live run always writes a terminal status
+        # after itself). This replaces the unsafe reclaim-in-__init__.
+        self.store.reclaim_stale_running()
+        for job in self.store.due(now):
+            # Atomic claim: only run if WE flipped it scheduled->running. Guards against
+            # ever double-running a job (defense-in-depth alongside the TickLock).
+            if not self.store.claim_for_run(job.id):
+                continue
+            success = await self._run_one(job)
+            self._record(job, now, success)
+            (result.ran if success else result.failed).append(job.id)
+        return result
+
+    async def _run_one(self, job: CronJob) -> bool:
+        try:
+            return bool(await asyncio.wait_for(
+                self.runner(job), timeout=max(job.max_duration_seconds, 0.001),
+            ))
+        except asyncio.TimeoutError:
+            logger.warning("cron job %s timed out after %ss", job.id, job.max_duration_seconds)
+            return False
+        except Exception as e:  # runner blew up — never crash the tick
+            logger.error("cron job %s raised: %s", job.id, e, exc_info=True)
+            return False
+
+    def _record(self, job: CronJob, now: datetime, success: bool) -> None:
+        if job.one_shot:
+            self.store.update_after_run(
+                job.id, last_run_at=now, next_run_at=None,
+                status="done" if success else "failed",
+            )
+            return
+        # recurring: reschedule from the schedule spec
+        try:
+            nxt = parse_schedule(job.schedule_spec).next_run_after(now)
+        except ScheduleError:
+            nxt = None
+        status = "scheduled" if nxt else "done"
+        self.store.update_after_run(job.id, last_run_at=now, next_run_at=nxt, status=status)

cron/service.py

@@ -0,0 +1,57 @@
+"""CronService — the schedule/list/cancel API over the job store (roadmap P5).
+
+Thin, fully testable orchestration of :mod:`cron.schedule` + :mod:`cron.jobs`.
+The agent-facing ``cronjob`` tool (``tools/cronjob_tools.py``) and any HTTP/CLI
+surface delegate here so scheduling logic lives in exactly one place.
+"""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional
+
+from cron.jobs import CronJob, CronJobStore
+from cron.schedule import ScheduleError, parse_schedule
+
+_DEFAULT_MAX_DURATION_S = 180  # 3-minute hard cap for cron sessions
+
+
+class CronService:
+    def __init__(self, store: CronJobStore, *, now: Optional[Callable[[], datetime]] = None,
+                 id_factory: Optional[Callable[[], str]] = None):
+        self.store = store
+        self._now = now or datetime.now
+        self._id = id_factory or (lambda: uuid.uuid4().hex[:12])
+
+    def schedule(self, *, task: str, schedule_spec: str, user_id: str,
+                 payload: Optional[Dict[str, Any]] = None,
+                 max_duration_seconds: int = _DEFAULT_MAX_DURATION_S,
+                 job_id: Optional[str] = None) -> CronJob:
+        """Validate the spec, compute the first run, and persist the job.
+
+        Raises ScheduleError for an unparseable spec or one with no future run
+        (e.g. a one-shot timestamp already in the past).
+
+        NOTE (ME-D2): ``skip_memory`` was removed from this signature — it was
+        never consumed by the runner or the goal dispatcher (dead, inert knob).
+        A cron run gets cross-session memory recall like any other session; see
+        ``CronJob.skip_memory`` in ``cron/jobs.py`` for the dormant DB column.
+        """
+        schedule = parse_schedule(schedule_spec)  # raises ScheduleError
+        now = self._now()
+        next_run = schedule.next_run_after(now)
+        if next_run is None:
+            raise ScheduleError(f"schedule {schedule_spec!r} has no future run time")
+        job = CronJob(
+            id=job_id or self._id(), task=task, schedule_spec=schedule_spec,
+            user_id=user_id, next_run_at=next_run, one_shot=schedule.one_shot,
+            max_duration_seconds=max_duration_seconds,
+            payload=payload or {}, created_at=now,
+        )
+        return self.store.add(job)
+
+    def list_jobs(self, user_id: Optional[str] = None) -> List[CronJob]:
+        return self.store.list(user_id=user_id)
+
+    def cancel(self, job_id: str, *, user_id: Optional[str] = None) -> bool:
+        return self.store.cancel(job_id, user_id=user_id)

cron/wake_gate.py

@@ -0,0 +1,223 @@
+"""Wake change-gate: skip a change-gated cron
+review tick when nothing observable changed since the last tick.
+
+The observed autonomy economy was ~23/25 no-op review wakes — every tick paid
+for a full model run to conclude "nothing new". The gate computes a cheap
+fingerprint over the tenant's observable autonomy state (goal board + goal
+events + cron activity + newest episode) and compares it to the baseline stored
+at the previous tick; equality means the paid model call is skipped ($0 tick,
+same shape as ``wake_agent=False``).
+
+Scope guards (both must hold before a tick can be skipped):
+- global: ``AutonomyConfig.wake_change_gate()`` (``WAKE_CHANGE_GATE``, posture
+  ``full`` turns it on by default — it pairs with ``CRON_ENABLED``);
+- per-job: ``payload.change_gated`` truthy AND no ``payload.deliver`` — a
+  scheduled delivery (daily digest) must fire even with zero change.
+
+Fail-open everywhere: a missing DB, a schema surprise, or any exception in a
+fingerprint source contributes a neutral value or disables the skip — the gate
+can only ever suppress a tick when every read succeeded AND matched the
+baseline. The baseline is recorded AFTER a run, tagged with the run's outcome
+(``record_wake_outcome``): a skip requires the last gated run to have SUCCEEDED,
+so a persistently-failing job (which mutates no observable state and would
+otherwise fingerprint as "unchanged") always retries instead of being silently
+swallowed.
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import sqlite3
+import time
+from typing import Any, Callable, Optional
+
+from core.sqlite_util import execute_retry
+
+logger = logging.getLogger(__name__)
+
+
+def _neutral_on_missing_table(fn: Callable[[], str], neutral: str) -> str:
+    """A missing table/DB is a known-empty source (nothing to observe) → a stable
+    neutral token. Any OTHER error re-raises so the caller's fail-open varying
+    token forces the tick to run."""
+    try:
+        return fn()
+    except sqlite3.OperationalError as e:
+        if "no such table" in str(e).lower():
+            return neutral
+        raise
+
+
+class WakeGateStore:
+    """Per-job fingerprint baselines, colocated in cron.db (the gate is a cron
+    concern; a side table keeps the baseline server-owned and out of the
+    agent-mutable job payload)."""
+
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        os.makedirs(os.path.dirname(db_path) or ".", exist_ok=True)
+        execute_retry(
+            db_path,
+            """CREATE TABLE IF NOT EXISTS wake_gate (
+                   job_id TEXT PRIMARY KEY,
+                   user_id TEXT,
+                   fingerprint TEXT NOT NULL,
+                   ok INTEGER NOT NULL DEFAULT 1,
+                   updated_at REAL NOT NULL
+               )""",
+        )
+        try:  # idempotent migration for pre-`ok` tables
+            execute_retry(db_path, "ALTER TABLE wake_gate ADD COLUMN ok INTEGER NOT NULL DEFAULT 1")
+        except sqlite3.OperationalError:
+            pass
+
+    def get(self, job_id: str) -> Optional[dict]:
+        row = execute_retry(
+            self.db_path, "SELECT fingerprint, ok FROM wake_gate WHERE job_id=?",
+            (job_id,), fetch="one",
+        )
+        return dict(row) if row else None
+
+    def put(self, job_id: str, user_id: str, fingerprint: str, *, ok: bool = True) -> None:
+        execute_retry(
+            self.db_path,
+            """INSERT INTO wake_gate (job_id, user_id, fingerprint, ok, updated_at)
+               VALUES (?,?,?,?,?)
+               ON CONFLICT(job_id) DO UPDATE SET
+                   fingerprint=excluded.fingerprint, ok=excluded.ok,
+                   updated_at=excluded.updated_at""",
+            (job_id, user_id, fingerprint, 1 if ok else 0, time.time()),
+        )
+
+
+def _goal_board_cursor(user_id: str, data_dir: str) -> str:
+    """MAX(goal_events.id) for the tenant + goal counts by status — bumps on every
+    goal/ask/objective mutation (goal_events is AUTOINCREMENT)."""
+    db = os.path.join(data_dir, "goals.db")
+    if not os.path.exists(db):
+        return "goals:none"
+    return _neutral_on_missing_table(lambda: _goal_board_read(user_id, db), "goals:none")
+
+
+def _goal_board_read(user_id: str, db: str) -> str:
+    max_ev = execute_retry(
+        db,
+        "SELECT MAX(e.id) AS m FROM goal_events e JOIN goals g ON g.id=e.goal_id "
+        "WHERE g.user_id=?",
+        (user_id,), fetch="one",
+    )
+    counts = execute_retry(
+        db,
+        "SELECT status, COUNT(*) AS n FROM goals WHERE user_id=? GROUP BY status "
+        "ORDER BY status",
+        (user_id,), fetch="all",
+    )
+    count_sig = ",".join(f"{r['status']}={r['n']}" for r in (counts or []))
+    return f"goals:{(max_ev or {})['m'] if max_ev else None}:{count_sig}"
+
+
+def _cron_cursor(user_id: str, data_dir: str, exclude_job_id: Optional[str]) -> str:
+    """Newest last_run_at across the tenant's OTHER cron jobs (another job having
+    run is observable change for a review tick)."""
+    db = os.path.join(data_dir, "cron.db")
+    if not os.path.exists(db):
+        return "cron:none"
+
+    def read() -> str:
+        row = execute_retry(
+            db,
+            "SELECT MAX(last_run_at) AS m FROM cron_jobs WHERE user_id=? AND id != ?",
+            (user_id, exclude_job_id or ""), fetch="one",
+        )
+        return f"cron:{row['m'] if row else None}"
+
+    return _neutral_on_missing_table(read, "cron:none")
+
+
+def _episode_cursor(user_id: str, data_dir: str) -> str:
+    """Newest episode row for the tenant (a completed session/goal/cron run since
+    the last tick is observable change). Reads the memory DB directly and
+    fail-opens to neutral on any surprise — the provider owns the schema."""
+    for name in ("memory.db",):
+        db = os.path.join(data_dir, name)
+        if not os.path.exists(db):
+            continue
+        def read() -> str:
+            row = execute_retry(
+                db, "SELECT MAX(id) AS m FROM episodes WHERE user_id=?",
+                (user_id,), fetch="one",
+            )
+            return f"episodes:{row['m'] if row else None}"
+
+        return _neutral_on_missing_table(read, "episodes:none")
+    return "episodes:none"
+
+
+def compute_wake_fingerprint(
+    user_id: str, *, data_dir: str, exclude_job_id: Optional[str] = None
+) -> str:
+    """Stable hash of the tenant's observable autonomy state (cheap, no LLM)."""
+    parts = []
+    for source in (
+        lambda: _goal_board_cursor(user_id, data_dir),
+        lambda: _cron_cursor(user_id, data_dir, exclude_job_id),
+        lambda: _episode_cursor(user_id, data_dir),
+    ):
+        try:
+            parts.append(source())
+        except Exception:
+            # a failing source contributes a per-call-varying token so the
+            # fingerprint reads as "changed" — fail-open, never suppress a wake
+            parts.append(f"err:{time.time()}")
+    return hashlib.sha256("|".join(parts).encode()).hexdigest()
+
+
+def gate_applies(job: Any) -> bool:
+    """Both guards: the global flag AND the per-job opt-in (never delivery jobs)."""
+    try:
+        from agents.task.constants import AutonomyConfig
+        if not AutonomyConfig.wake_change_gate():
+            return False
+        payload = dict(getattr(job, "payload", None) or {})
+        return bool(payload.get("change_gated")) and not payload.get("deliver")
+    except Exception:
+        return False
+
+
+def should_skip_wake(job: Any, *, data_dir: str) -> bool:
+    """Whether this change-gated tick can be skipped ($0). READ-ONLY: a skip
+    requires an existing baseline that (a) matches the current fingerprint and
+    (b) was recorded after a SUCCESSFUL run — a failed run never establishes a
+    skippable baseline, so failing jobs always retry. Callers record the
+    baseline after the run via :func:`record_wake_outcome`."""
+    try:
+        if not gate_applies(job):
+            return False
+        store = WakeGateStore(os.path.join(data_dir, "cron.db"))
+        baseline = store.get(job.id)
+        if not baseline or not baseline.get("ok"):
+            return False
+        fp = compute_wake_fingerprint(
+            job.user_id, data_dir=data_dir, exclude_job_id=getattr(job, "id", None)
+        )
+        return fp == baseline.get("fingerprint")
+    except Exception:
+        logger.warning("wake gate error — failing open (running the tick)", exc_info=True)
+        return False
+
+
+def record_wake_outcome(job: Any, *, data_dir: str, ok: bool) -> None:
+    """Record the post-run baseline (fingerprint computed AFTER the run, so the
+    run's own writes don't read as 'change' next tick) tagged with the outcome.
+    Fail-open — a store error just means the next tick runs."""
+    try:
+        if not gate_applies(job):
+            return
+        store = WakeGateStore(os.path.join(data_dir, "cron.db"))
+        fp = compute_wake_fingerprint(
+            job.user_id, data_dir=data_dir, exclude_job_id=getattr(job, "id", None)
+        )
+        store.put(job.id, job.user_id, fp, ok=ok)
+    except Exception:
+        logger.warning("wake gate outcome record failed (next tick will run)", exc_info=True)

data/__init__.py

@@ -0,0 +1 @@
+"""POLYROB seed data (prompts, etc.) shipped with the package."""