coding-os 0.3.2__py3-none-any.whl

scheduled/_state.py

@@ -0,0 +1,113 @@
+"""State read/write for scheduled job runs."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger("codingos.scheduled.state")
+
+_STATE_FILE = "last_run.json"
+_SCHEDULED_DIR = "scheduled"
+
+
+def state_dir(project_root: Path) -> Path:
+    return project_root / ".coding-os" / _SCHEDULED_DIR
+
+
+def state_path(project_root: Path) -> Path:
+    return state_dir(project_root) / _STATE_FILE
+
+
+def read_state(project_root: Path) -> dict:
+    """Read last_run.json for a project; returns {} if missing."""
+    path = state_path(project_root)
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.debug("read_state failed for %s: %s", project_root, exc)
+        return {}
+
+
+def write_state(project_root: Path, state: dict) -> None:
+    """Write last_run.json atomically (flock-protected)."""
+    sdir = state_dir(project_root)
+    sdir.mkdir(parents=True, exist_ok=True)
+    path = state_path(project_root)
+    lock_path = path.with_suffix(".lock")
+
+    try:
+        with open(lock_path, "w") as lock_f:
+            fcntl.flock(lock_f, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            try:
+                tmp = path.with_suffix(".tmp")
+                tmp.write_text(json.dumps(state, indent=2, default=str))
+                tmp.replace(path)
+            finally:
+                fcntl.flock(lock_f, fcntl.LOCK_UN)
+    except BlockingIOError:
+        logger.warning("write_state: lock contention for %s — skipping write", project_root)
+    except OSError as exc:
+        logger.warning("write_state failed for %s: %s", project_root, exc)
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def days_since_marker(marker_path: Path) -> float | None:
+    """Return days since marker file was last modified; None if missing."""
+    if not marker_path.exists():
+        return None
+    try:
+        mtime = marker_path.stat().st_mtime
+        elapsed = datetime.now(timezone.utc).timestamp() - mtime
+        return max(0.0, elapsed / 86400.0)
+    except OSError as exc:
+        logger.debug("days_since_marker error: %s", exc)
+        return None
+
+
+def touch_marker(marker_path: Path) -> None:
+    """Write current ISO timestamp to marker file."""
+    try:
+        marker_path.parent.mkdir(parents=True, exist_ok=True)
+        marker_path.write_text(now_iso())
+    except OSError as exc:
+        logger.warning("touch_marker failed for %s: %s", marker_path, exc)
+
+
+def read_registry(hub_state_dir: Path | None = None) -> list[dict]:
+    """Read ~/.coding-os/registry.json → list of {slug, path} dicts.
+
+    Fallback: COS_PROJECT_ROOT env → [{slug: 'local', path: cwd}].
+    """
+    candidates: list[Path] = []
+    if hub_state_dir:
+        candidates.append(hub_state_dir / "registry.json")
+    candidates.append(Path.home() / ".coding-os" / "registry.json")
+
+    for reg_path in candidates:
+        if reg_path.exists():
+            try:
+                data = json.loads(reg_path.read_text())
+                projects = data.get("projects", [])
+                if projects:
+                    return projects
+            except (json.JSONDecodeError, OSError) as exc:
+                logger.warning("read_registry failed for %s: %s", reg_path, exc)
+
+    env_root = os.environ.get("COS_PROJECT_ROOT", "")
+    if env_root:
+        logger.info("registry not found; using COS_PROJECT_ROOT=%s", env_root)
+        return [{"slug": Path(env_root).name, "path": env_root}]
+
+    cwd = str(Path.cwd())
+    logger.info("registry not found; falling back to cwd=%s", cwd)
+    return [{"slug": Path(cwd).name, "path": cwd}]

scheduled/config.py

@@ -0,0 +1,86 @@
+"""Scheduled-maintenance config — cron cadence + responsive thresholds.
+
+Per-project JSON at ``<proj>/.coding-os/scheduled/config.json`` read by the
+nightly daemon, the responsive session-end trigger, and the Hub
+(``GET``/``PUT /api/scheduled/config``). Missing keys fall back to defaults so
+an absent file behaves exactly as the old hardcoded constants did.
+
+Contract: docs/engineering/scheduled-jobs.md § Configurable cadence.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from scheduled._state import state_dir
+
+_CONFIG_FILE = "config.json"
+
+DEFAULTS: dict[str, object] = {
+    "enabled": True,
+    "hour": 3,
+    "decay_throttle_days": 7,
+    "learn_extract_min_outcomes": 3,
+    "responsive_extract_threshold": 5,
+    "archive_prune_days": 90,
+    "error_sweep_occ_threshold": 3,
+    "error_sweep_session_threshold": 2,
+}
+
+# (key, lo, hi) bounds for integer fields — values are clamped on save.
+_INT_BOUNDS: dict[str, tuple[int, int]] = {
+    "hour": (0, 23),
+    "decay_throttle_days": (1, 365),
+    "learn_extract_min_outcomes": (1, 1000),
+    "responsive_extract_threshold": (1, 1000),
+    "archive_prune_days": (7, 3650),
+    "error_sweep_occ_threshold": (1, 1000),
+    "error_sweep_session_threshold": (1, 1000),
+}
+
+
+def config_path(project_root: Path | str) -> Path:
+    return state_dir(Path(project_root)) / _CONFIG_FILE
+
+
+def _coerce(key: str, value: object) -> object:
+    if key == "enabled":
+        return bool(value)
+    bounds = _INT_BOUNDS.get(key)
+    if bounds is None:  # future DEFAULTS key without declared bounds — don't crash
+        return DEFAULTS[key]
+    lo, hi = bounds
+    try:
+        return max(lo, min(hi, int(value)))  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return DEFAULTS[key]
+
+
+def load_config(project_root: Path | str) -> dict:
+    """Return the project's scheduled config, defaults filled for missing keys."""
+    cfg = dict(DEFAULTS)
+    path = config_path(project_root)
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return cfg
+    if isinstance(raw, dict):
+        for key in DEFAULTS:
+            if key in raw:
+                cfg[key] = _coerce(key, raw[key])
+    return cfg
+
+
+def save_config(project_root: Path | str, updates: dict) -> dict:
+    """Merge validated updates into the project's config and persist atomically."""
+    cfg = load_config(project_root)
+    for key, value in updates.items():
+        if key in DEFAULTS:
+            cfg[key] = _coerce(key, value)
+    path = config_path(project_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
+    tmp.replace(path)
+    return cfg

scheduled/dep_reconcile.py

@@ -0,0 +1,135 @@
+"""Dependency-readiness reconciler (CRON A task).
+
+Closes the gaps the per-completion cascade (board_os.cascade_ready_dependents)
+cannot cover, because that cascade only fires at the instant ONE dependency
+transitions to ``complete``:
+
+(a) re-block — a ready/icebox task whose dependency was reverted out of
+    ``complete`` is moved back to ``blocked`` with a reason naming the reopened
+    dependency;
+(b) needs-authoring — a task now dependency-unblocked but with an incomplete
+    Definition-of-Ready body is surfaced (reusing cascade_ready_dependents over
+    every complete task, not re-implemented);
+(c) long-blocked — a task blocked beyond a day threshold is surfaced for human
+    review.
+
+See docs/engineering/scheduled-jobs.md for the full contract.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+
+DEFAULT_BLOCKED_REVIEW_DAYS = 14
+
+
+def _reblock_reopened(conn: sqlite3.Connection, *, dry_run: bool) -> list[dict]:
+    """Move ready/icebox tasks back to blocked when a dependency left 'complete'."""
+    from board_os.mcp_tools import (
+        READY_LABEL,
+        _labels_list_from_json,
+        cos_task_move,
+    )
+    from board_os.workflow import incomplete_dependencies
+
+    rows = conn.execute("SELECT task_id, labels_json FROM tasks WHERE status = 'icebox'").fetchall()
+
+    reblocked: list[dict] = []
+    for task_id, labels_json in rows:
+        if READY_LABEL not in _labels_list_from_json(labels_json):
+            continue
+        pending = incomplete_dependencies(conn, str(task_id))
+        if not pending:
+            continue
+        reason = f"dependency reopened — re-blocked: waiting on {', '.join(pending)}"
+        entry = {"task_id": str(task_id), "reason": reason, "pending": pending}
+        if not dry_run:
+            # icebox→blocked is not a state-machine edge (valid from icebox:
+            # in_progress/emergency/archive), so force the deliberate re-block.
+            env = json.loads(
+                cos_task_move(conn, task_id=str(task_id), to="blocked", reason=reason, force=True)
+            )
+            if not env.get("ok"):
+                entry["move_failed"] = env.get("error")
+        reblocked.append(entry)
+    return reblocked
+
+
+def _surface_unblocked(conn: sqlite3.Connection, *, dry_run: bool) -> dict[str, list]:
+    """Reuse cascade_ready_dependents over every complete task to re-classify
+    its dependents — aggregating those auto-readied vs. still needs-authoring."""
+    from board_os.mcp_tools import cascade_ready_dependents
+
+    complete_ids = [
+        str(r[0])
+        for r in conn.execute("SELECT task_id FROM tasks WHERE status = 'complete'").fetchall()
+    ]
+
+    readied: list[str] = []
+    needs_authoring: list[dict] = []
+    seen_authoring: set[str] = set()
+    for completed_id in complete_ids:
+        if dry_run:
+            # The cascade mutates (auto-ready); a dry run must not. Counts for
+            # this branch are intentionally omitted rather than re-implemented.
+            continue
+        report = cascade_ready_dependents(conn, completed_id)
+        readied.extend(report.get("readied", []))
+        for item in report.get("needs_authoring", []):
+            tid = item.get("task_id")
+            if tid and tid not in seen_authoring:
+                seen_authoring.add(tid)
+                needs_authoring.append(item)
+    return {"readied": readied, "needs_authoring": needs_authoring}
+
+
+def _surface_long_blocked(conn: sqlite3.Connection, *, review_days: int) -> list[dict]:
+    """Surface tasks blocked longer than review_days for human review (read-only)."""
+    now = int(time.time())
+    cutoff = now - review_days * 86400
+    rows = conn.execute(
+        "SELECT task_id, "
+        "  (SELECT MAX(transitioned_at) FROM task_status_history h "
+        "   WHERE h.task_id = tasks.task_id AND h.new_status = 'blocked') "
+        "FROM tasks WHERE status = 'blocked'"
+    ).fetchall()
+
+    surfaced: list[dict] = []
+    for task_id, blocked_at in rows:
+        if blocked_at is None or int(blocked_at) > cutoff:
+            continue
+        blocked_days = (now - int(blocked_at)) // 86400
+        surfaced.append({"task_id": str(task_id), "blocked_days": blocked_days})
+    return surfaced
+
+
+def run_dep_reconcile(
+    conn: sqlite3.Connection,
+    *,
+    dry_run: bool,
+    blocked_review_days: int = DEFAULT_BLOCKED_REVIEW_DAYS,
+) -> dict:
+    """Run all three reconciler branches over the whole task graph."""
+    if (
+        conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='tasks'").fetchone()
+        is None
+    ):
+        return {"status": "skipped", "reason": "tasks table not present"}
+
+    reblocked = _reblock_reopened(conn, dry_run=dry_run)
+    unblocked = _surface_unblocked(conn, dry_run=dry_run)
+    long_blocked = _surface_long_blocked(conn, review_days=blocked_review_days)
+
+    if not dry_run:
+        conn.commit()
+
+    return {
+        "status": "ok",
+        "reblocked": reblocked,
+        "readied": unblocked["readied"],
+        "needs_authoring": unblocked["needs_authoring"],
+        "long_blocked": long_blocked,
+        "dry_run": dry_run,
+    }

scheduled/error_sweep.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import sqlite3
+from typing import Callable
+
+# Reserved scope for the sweep's own diagnostics — EXCLUDED from its input so a
+# sweep error can never file a bug task about itself (anti-recursion invariant).
+SWEEP_SCOPE = "ops.error_sweep"
+
+_SEV = {"DEBUG": 10, "INFO": 20, "OK": 21, "WARN": 30, "ERROR": 40, "FATAL": 50}
+
+
+def rollup_fingerprints(conn: sqlite3.Connection) -> int:
+    """Recompute log_fingerprints aggregates from log_events. Idempotent. Returns fingerprint count."""
+    conn.row_factory = sqlite3.Row
+    has_class = any(r[1] == "event_class" for r in conn.execute("PRAGMA table_info(log_events)"))
+    class_filter = " AND COALESCE(event_class, 'fault') = 'fault'" if has_class else ""
+    rows = conn.execute(
+        "SELECT fingerprint, scope, exc_type, msg, lvl, ts, session_id "
+        "FROM log_events WHERE scope != ? AND lvl IN ('WARN', 'ERROR', 'FATAL')" + class_filter,
+        (SWEEP_SCOPE,),
+    ).fetchall()
+    agg: dict[str, dict] = {}
+    for r in rows:
+        a = agg.get(r["fingerprint"])
+        if a is None:
+            a = agg[r["fingerprint"]] = {
+                "scope": r["scope"],
+                "exc_type": r["exc_type"],
+                "sample_msg": r["msg"],
+                "max_lvl": r["lvl"],
+                "first_seen": r["ts"],
+                "last_seen": r["ts"],
+                "count": 0,
+                "sessions": set(),
+            }
+        a["count"] += 1
+        if r["ts"] < a["first_seen"]:
+            a["first_seen"] = r["ts"]
+        if r["ts"] > a["last_seen"]:
+            a["last_seen"] = r["ts"]
+        if _SEV.get(r["lvl"], 0) > _SEV.get(a["max_lvl"], 0):
+            a["max_lvl"] = r["lvl"]
+            a["sample_msg"] = r["msg"]
+        if r["session_id"]:
+            a["sessions"].add(r["session_id"])
+    for fp, a in agg.items():
+        conn.execute(
+            "INSERT INTO log_fingerprints "
+            "(fingerprint, scope, exc_type, sample_msg, max_lvl, first_seen, last_seen, "
+            " count, distinct_sessions) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) "
+            "ON CONFLICT(fingerprint) DO UPDATE SET "
+            "  last_seen = excluded.last_seen, count = excluded.count, "
+            "  distinct_sessions = excluded.distinct_sessions, max_lvl = excluded.max_lvl, "
+            "  sample_msg = excluded.sample_msg",
+            (
+                fp,
+                a["scope"],
+                a["exc_type"],
+                a["sample_msg"],
+                a["max_lvl"],
+                a["first_seen"],
+                a["last_seen"],
+                a["count"],
+                len(a["sessions"]),
+            ),
+        )
+    # Reconcile: an open fingerprint with no remaining fault-class events (e.g.
+    # reclassified to policy) is stale — drop it so it is never filed as a bug.
+    open_fps = [
+        r[0] for r in conn.execute("SELECT fingerprint FROM log_fingerprints WHERE status = 'open'")
+    ]
+    for fp in open_fps:
+        if fp not in agg:
+            conn.execute(
+                "DELETE FROM log_fingerprints WHERE fingerprint = ? AND status = 'open'", (fp,)
+            )
+    conn.commit()
+    return len(agg)
+
+
+def select_for_filing(
+    conn: sqlite3.Connection, *, occ_threshold: int, session_threshold: int
+) -> list[tuple[sqlite3.Row, str]]:
+    """Open fingerprints worth a task: FATAL always, ERROR past occurrence/session threshold.
+
+    A non-FATAL fingerprint seen in zero distinct sessions is never filed: an
+    agent-visible recurring error always carries a session_id, so a session-less
+    cluster is machine/test noise (e.g. the deliberate error-path test fixtures
+    that pollute the durable store) — not a bug the agent can pull and fix.
+    """
+    conn.row_factory = sqlite3.Row
+    out: list[tuple[sqlite3.Row, str]] = []
+    for r in conn.execute("SELECT * FROM log_fingerprints WHERE status = 'open'").fetchall():
+        if r["max_lvl"] == "FATAL":
+            out.append((r, "fatal"))
+        elif r["distinct_sessions"] < 1:
+            continue  # no real session → not an agent-visible error
+        elif r["count"] >= occ_threshold or r["distinct_sessions"] >= session_threshold:
+            out.append((r, "error"))
+    return out
+
+
+def run_error_sweep(
+    conn: sqlite3.Connection,
+    *,
+    create_bug_task: Callable[[sqlite3.Row, str], "str | None"],
+    occ_threshold: int = 3,
+    session_threshold: int = 2,
+    dry_run: bool = False,
+) -> dict:
+    """Roll up, select over-threshold fingerprints, and file one idempotent bug task each.
+
+    create_bug_task(row, severity) -> task_id is injected so the sweep logic stays
+    pure + testable. Idempotent: only status='open' fingerprints are filed; once
+    filed they flip to 'filed' and are never re-selected.
+    """
+    rolled = rollup_fingerprints(conn)
+    candidates = select_for_filing(
+        conn, occ_threshold=occ_threshold, session_threshold=session_threshold
+    )
+    filed: list[dict] = []
+    for row, severity in candidates:
+        if dry_run:
+            filed.append({"fingerprint": row["fingerprint"], "severity": severity, "dry_run": True})
+            continue
+        task_id = create_bug_task(row, severity)
+        if task_id:
+            conn.execute(
+                "UPDATE log_fingerprints SET task_id = ?, status = 'filed' WHERE fingerprint = ?",
+                (task_id, row["fingerprint"]),
+            )
+            filed.append(
+                {"fingerprint": row["fingerprint"], "task_id": task_id, "severity": severity}
+            )
+    conn.commit()
+    return {"rolled_up": rolled, "candidates": len(candidates), "filed": filed}