ultra-builder-pro-cli 0.6.0 → 0.8.1

package/hooks/health_check.py

@@ -1,59 +1,157 @@
 #!/usr/bin/env python3
-"""Advisory health check for an active Ultra workflow.
-
-No memory, prompt, transcript, or generic host policy is inspected here.
-"""
+"""Fast, read-only Ultra runtime health inspection at session start."""
 
 import json
 import sqlite3
 import sys
 from pathlib import Path
 
-TERMINAL = {"committed", "completed", "done", "cancelled"}
-REQUIRED_TABLES = {"tasks", "events", "sessions", "schema_version"}
+
+REQUIRED_TABLES = {
+    "tasks", "events", "sessions", "schema_version", "migration_history",
+    "telemetry", "specs_refs", "circuit_breaker", "changes", "artifacts",
+    "context_snapshots", "trace_links", "incidents", "projection_jobs",
+    "event_consumers",
+}
 
 
-def main():
+def hook_input() -> dict:
     try:
-        raw = sys.stdin.read()
-        data = json.loads(raw) if raw.strip() else {}
-    except (json.JSONDecodeError, OSError) as exc:
+        value = json.loads(sys.stdin.read() or "{}")
+        return value if isinstance(value, dict) else {}
+    except json.JSONDecodeError as exc:
         print(f"[health_check] invalid hook input: {exc}", file=sys.stderr)
-        data = {}
-    start = Path(data.get("cwd") or Path.cwd()).resolve()
-    root = None
-    state = None
+        return {}
+
+
+def find_root(start: Path):
     for candidate in (start, *start.parents):
-        state_file = candidate / ".ultra" / "workflow-state.json"
-        if state_file.is_file():
-            try:
-                value = json.loads(state_file.read_text(encoding="utf-8"))
-            except (OSError, json.JSONDecodeError) as exc:
-                print(f"[health_check] cannot read {state_file}: {exc}", file=sys.stderr)
-                value = None
-            if isinstance(value, dict) and value.get("status") not in TERMINAL:
-                root, state = candidate, value
-            break
-    if root is None or state is None:
-        print(json.dumps({}))
-        return
-    issues = []
+        ultra = candidate / ".ultra"
+        if (
+            (ultra / "state.db").is_file()
+            or (ultra / "workflow-state.json").is_file()
+            or (ultra / "changes" / "active").is_dir()
+        ):
+            return candidate
+    return None
+
+
+def inspect(root: Path) -> dict:
     db_path = root / ".ultra" / "state.db"
+    report = {"status": "healthy", "project": str(root), "checks": {}}
+    issues = []
     if not db_path.is_file():
-        issues.append(".ultra/state.db is missing")
-    else:
-        try:
-            with sqlite3.connect(str(db_path), timeout=1) as conn:
-                tables = {row[0] for row in conn.execute(
+        report["checks"]["state_db"] = {"status": "fail", "reason": "missing"}
+        report["status"] = "degraded"
+        return report
+
+    try:
+        uri = f"file:{db_path}?mode=ro"
+        with sqlite3.connect(uri, uri=True, timeout=1) as conn:
+            quick = conn.execute("PRAGMA quick_check").fetchone()[0]
+            tables = {
+                row[0] for row in conn.execute(
                     "SELECT name FROM sqlite_master WHERE type='table'"
-                )}
+                )
+            }
             missing = sorted(REQUIRED_TABLES - tables)
+            report["checks"]["state_db"] = {
+                "status": "pass" if quick == "ok" and not missing else "fail",
+                "integrity": quick,
+                "missing_tables": missing,
+            }
+            if quick != "ok" or missing:
+                issues.append("state_db")
             if missing:
-                issues.append(f"state.db missing tables: {', '.join(missing)}")
-        except sqlite3.Error as exc:
-            issues.append(f"state.db unreadable: {exc}")
+                report["status"] = "degraded"
+                return report
+
+            incidents = [
+                {"id": row[0], "code": row[1], "severity": row[2], "retryable": bool(row[3])}
+                for row in conn.execute(
+                    """SELECT id, code, severity, retryable FROM incidents
+                       WHERE status = 'open' ORDER BY last_seen_at DESC LIMIT 20"""
+                )
+            ]
+            report["checks"]["incidents"] = {
+                "status": "pass" if not incidents else "fail",
+                "open": incidents,
+            }
+            if incidents:
+                issues.append("incidents")
+
+            pending = conn.execute(
+                "SELECT COUNT(*) FROM projection_jobs WHERE status = 'pending'"
+            ).fetchone()[0]
+            running = conn.execute(
+                "SELECT COUNT(*) FROM projection_jobs WHERE status = 'running'"
+            ).fetchone()[0]
+            failed = conn.execute(
+                "SELECT COUNT(*) FROM projection_jobs WHERE status = 'failed'"
+            ).fetchone()[0]
+            event_cursor = conn.execute(
+                "SELECT COALESCE(MAX(id), 0) FROM events"
+            ).fetchone()[0]
+            projected_cursor = conn.execute(
+                """SELECT COALESCE(MAX(event_cursor), 0) FROM projection_jobs
+                   WHERE status = 'completed'"""
+            ).fetchone()[0]
+            projection_ok = (
+                pending == 0 and running == 0 and failed == 0
+                and event_cursor <= projected_cursor
+            )
+            report["checks"]["projections"] = {
+                "status": "pass" if projection_ok else "fail",
+                "pending": pending,
+                "running": running,
+                "failed": failed,
+                "event_cursor": event_cursor,
+                "projected_cursor": projected_cursor,
+            }
+            if not projection_ok:
+                issues.append("projections")
+
+            orphan = conn.execute(
+                "SELECT COUNT(*) FROM sessions WHERE status = 'orphan'"
+            ).fetchone()[0]
+            report["checks"]["sessions"] = {
+                "status": "pass" if orphan == 0 else "fail", "orphan": orphan,
+            }
+            if orphan:
+                issues.append("sessions")
+
+            missing_artifacts = []
+            for change_id, artifact_root in conn.execute(
+                """SELECT id, artifact_root FROM changes
+                   WHERE status IN ('active', 'blocked', 'ready')"""
+            ):
+                if artifact_root and not (root / artifact_root).exists():
+                    missing_artifacts.append(change_id)
+            report["checks"]["change_artifacts"] = {
+                "status": "pass" if not missing_artifacts else "fail",
+                "missing": missing_artifacts,
+            }
+            if missing_artifacts:
+                issues.append("change_artifacts")
+    except sqlite3.Error as exc:
+        report["checks"]["state_db"] = {"status": "fail", "reason": str(exc)}
+        issues.append("state_db")
+
     if issues:
-        print("[Ultra health] " + "; ".join(issues), file=sys.stderr)
+        report["status"] = "degraded"
+    return report
+
+
+def main() -> None:
+    data = hook_input()
+    start = Path(data.get("cwd") or Path.cwd()).resolve()
+    root = find_root(start)
+    if root is None:
+        print(json.dumps({}))
+        return
+    report = inspect(root)
+    if report["status"] != "healthy":
+        print("[Ultra health] " + json.dumps(report, ensure_ascii=False, sort_keys=True), file=sys.stderr)
     print(json.dumps({}))
 
 

package/hooks/workflow_checkpoint.py

@@ -11,6 +11,17 @@ from pathlib import Path
 TERMINAL = {"committed", "completed", "done", "cancelled"}
 
 
+def valid_workflow(state: object) -> bool:
+    return (
+        isinstance(state, dict)
+        and isinstance(state.get("command"), str)
+        and bool(state["command"].strip())
+        and state.get("step") is not None
+        and isinstance(state.get("status"), str)
+        and bool(state["status"].strip())
+    )
+
+
 def main() -> None:
     try:
         data = json.loads(sys.stdin.read() or "{}")
@@ -28,7 +39,10 @@ def main() -> None:
         except (OSError, json.JSONDecodeError) as exc:
             print(f"[workflow_checkpoint] cannot read {state_file}: {exc}", file=sys.stderr)
             break
-        if not isinstance(state, dict) or state.get("status") in TERMINAL:
+        if not valid_workflow(state):
+            print(f"[workflow_checkpoint] invalid workflow state in {state_file}", file=sys.stderr)
+            break
+        if state.get("status") in TERMINAL:
             break
         runtime_dir = root / ".ultra" / "runtime"
         runtime_dir.mkdir(parents=True, exist_ok=True)

package/hooks/workflow_context.py

@@ -1,15 +1,16 @@
 #!/usr/bin/env python3
-"""Inject the live Ultra workflow state at session start.
-
-This hook is deliberately project-local and contains no cross-session memory.
-It is a no-op unless an active .ultra/workflow-state.json exists.
-"""
+"""Inject current Ultra workflow/change context without persistent memory."""
 
 import json
+import sqlite3
 import sys
 from pathlib import Path
 
-TERMINAL = {"committed", "completed", "done", "cancelled"}
+
+TERMINAL_WORKFLOW = {"committed", "completed", "done", "cancelled"}
+PROVIDER_FIELDS = {
+    "provider", "project", "reference", "revision", "indexed_head", "status",
+}
 
 
 def payload() -> dict:
@@ -21,38 +22,127 @@ def payload() -> dict:
         return {}
 
 
-def active_state(data: dict):
-    start = Path(data.get("cwd") or Path.cwd()).resolve()
+def find_root(start: Path):
     for root in (start, *start.parents):
-        state_file = root / ".ultra" / "workflow-state.json"
-        if not state_file.is_file():
-            continue
-        try:
-            state = json.loads(state_file.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            print(f"[workflow_context] cannot read {state_file}: {exc}", file=sys.stderr)
-            return None
-        if isinstance(state, dict) and state.get("status") not in TERMINAL:
-            return root, state
+        ultra = root / ".ultra"
+        if (
+            (ultra / "state.db").is_file()
+            or (ultra / "workflow-state.json").is_file()
+            or (ultra / "changes" / "active").is_dir()
+        ):
+            return root
+    return None
+
+
+def read_workflow(root: Path):
+    state_file = root / ".ultra" / "workflow-state.json"
+    if not state_file.is_file():
+        return None
+    try:
+        state = json.loads(state_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"[workflow_context] cannot read {state_file}: {exc}", file=sys.stderr)
         return None
+    if isinstance(state, dict) and state.get("status") not in TERMINAL_WORKFLOW:
+        return state
     return None
 
 
+def safe_json(raw, fallback):
+    try:
+        value = json.loads(raw)
+        return value
+    except (TypeError, json.JSONDecodeError):
+        return fallback
+
+
+def provider_metadata(raw) -> dict:
+    refs = safe_json(raw, {})
+    if not isinstance(refs, dict):
+        return {}
+    clean = {}
+    for kind, ref in refs.items():
+        if kind not in {"memory", "code_graph"} or not isinstance(ref, dict):
+            continue
+        clean[kind] = {key: ref[key] for key in PROVIDER_FIELDS if key in ref}
+    return clean
+
+
+def read_changes(root: Path):
+    db_path = root / ".ultra" / "state.db"
+    if not db_path.is_file():
+        return []
+    try:
+        with sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=1) as conn:
+            exists = conn.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name='changes'"
+            ).fetchone()
+            if not exists:
+                return []
+            rows = conn.execute(
+                """SELECT id, title, kind, status, intent, docs_impact_json,
+                          provider_refs_json, artifact_root
+                   FROM changes WHERE status IN ('active', 'blocked', 'ready')
+                   ORDER BY updated_at DESC"""
+            ).fetchall()
+    except sqlite3.Error as exc:
+        print(f"[workflow_context] cannot inspect {db_path}: {exc}", file=sys.stderr)
+        return []
+    return [
+        {
+            "id": row[0], "title": row[1], "kind": row[2], "status": row[3],
+            "intent": row[4], "docs_impact": safe_json(row[5], {}),
+            "providers": provider_metadata(row[6]), "artifact_root": row[7],
+        }
+        for row in rows
+    ]
+
+
+def context_text(root: Path, workflow, changes) -> str:
+    lines = []
+    if workflow:
+        lines.extend([
+            "[Ultra active workflow]",
+            f"Project: {root}",
+            f"Command: {workflow.get('command', 'unknown')}",
+            f"Task: {workflow.get('task_id', workflow.get('task', 'unknown'))}",
+            f"Step: {workflow.get('step', 'unknown')}",
+            f"Status: {workflow.get('status', 'active')}",
+        ])
+    if changes:
+        change = changes[0]
+        lines.extend([
+            "[Ultra continuous change]",
+            f"Project: {root}",
+            f"Change: {change['id']} ({change['kind']}, {change['status']})",
+            f"Title: {change['title']}",
+            f"Intent: {change['intent']}",
+            "Docs impact: " + json.dumps(change["docs_impact"], ensure_ascii=False, sort_keys=True),
+            f"Context manifest: {change['artifact_root']}/context-manifest.json",
+            "External providers (metadata references only): "
+            + json.dumps(change["providers"], ensure_ascii=False, sort_keys=True),
+        ])
+        if len(changes) > 1:
+            lines.append(f"Active change count: {len(changes)}; resolve scope with change.list before mutation.")
+    if not workflow and not changes:
+        lines.extend([
+            "[Ultra baseline]",
+            f"Project: {root}",
+            "No active continuous change. Start daily work with the ultra-change workflow.",
+        ])
+    lines.append("Authority: .ultra/state.db; generated JSON/Markdown are projections or artifacts.")
+    return "\n".join(lines)
+
+
 def main() -> None:
-    found = active_state(payload())
-    if not found:
+    data = payload()
+    root = find_root(Path(data.get("cwd") or Path.cwd()).resolve())
+    if root is None:
         print(json.dumps({}))
         return
-    root, state = found
-    context = "\n".join([
-        "[Ultra active workflow]",
-        f"Project: {root}",
-        f"Command: {state.get('command', 'unknown')}",
-        f"Task: {state.get('task_id', state.get('task', 'unknown'))}",
-        f"Step: {state.get('step', 'unknown')}",
-        f"Status: {state.get('status', 'active')}",
-        "Authority: .ultra/state.db; workflow recovery: .ultra/workflow-state.json.",
-    ])
+    workflow = read_workflow(root)
+    changes = read_changes(root)
+    context = context_text(root, workflow, changes)
     print(json.dumps({"hookSpecificOutput": {
         "hookEventName": "SessionStart",
         "additionalContext": context,

package/hooks/workflow_resume.py

@@ -2,12 +2,82 @@
 """Restore only the current Ultra workflow boundary after compaction."""
 
 import json
+import os
 import sys
+import tempfile
+from datetime import datetime, timezone
 from pathlib import Path
 
 TERMINAL = {"committed", "completed", "done", "cancelled"}
 
 
+def valid_workflow(state: object) -> bool:
+    return (
+        isinstance(state, dict)
+        and isinstance(state.get("command"), str)
+        and bool(state["command"].strip())
+        and state.get("step") is not None
+        and isinstance(state.get("status"), str)
+        and bool(state["status"].strip())
+    )
+
+
+def read_json(file: Path, label: str):
+    if not file.is_file():
+        return None
+    try:
+        return json.loads(file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"[workflow_resume] cannot read {label} {file}: {exc}", file=sys.stderr)
+        return None
+
+
+def parse_time(value: object):
+    if not isinstance(value, str) or not value.strip():
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
+    except ValueError:
+        return None
+
+
+def newest_time(file: Path, *values: object) -> datetime:
+    candidates = [parsed for value in values if (parsed := parse_time(value)) is not None]
+    try:
+        candidates.append(datetime.fromtimestamp(file.stat().st_mtime, tz=timezone.utc))
+    except OSError:
+        pass
+    return max(candidates, default=datetime.min.replace(tzinfo=timezone.utc))
+
+
+def load_checkpoint(file: Path):
+    checkpoint = read_json(file, "checkpoint")
+    if checkpoint is None:
+        return None
+    if not isinstance(checkpoint, dict):
+        print(f"[workflow_resume] invalid checkpoint schema in {file}", file=sys.stderr)
+        return None
+    captured_at = checkpoint.get("captured_at")
+    workflow = checkpoint.get("workflow")
+    if checkpoint.get("schema") != 1 or parse_time(captured_at) is None or not valid_workflow(workflow):
+        print(f"[workflow_resume] invalid checkpoint schema in {file}", file=sys.stderr)
+        return None
+    return checkpoint
+
+
+def restore_state(file: Path, state: dict) -> None:
+    file.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_name = tempfile.mkstemp(prefix="workflow-state.", suffix=".json", dir=file.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(state, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+        os.replace(temp_name, file)
+    finally:
+        if os.path.exists(temp_name):
+            os.unlink(temp_name)
+
+
 def main() -> None:
     try:
         data = json.loads(sys.stdin.read() or "{}")
@@ -18,21 +88,40 @@ def main() -> None:
     start = Path(data.get("cwd") or Path.cwd()).resolve()
     for root in (start, *start.parents):
         state_file = root / ".ultra" / "workflow-state.json"
-        if not state_file.is_file():
+        checkpoint_file = root / ".ultra" / "runtime" / "checkpoint.json"
+        if not state_file.is_file() and not checkpoint_file.is_file():
             continue
-        try:
-            state = json.loads(state_file.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            print(f"[workflow_resume] cannot read {state_file}: {exc}", file=sys.stderr)
+        live = read_json(state_file, "workflow state")
+        if live is not None and not valid_workflow(live):
+            print(f"[workflow_resume] invalid workflow state in {state_file}", file=sys.stderr)
+            live = None
+        if live is not None and live.get("status") in TERMINAL:
             break
-        if not isinstance(state, dict) or state.get("status") in TERMINAL:
+        checkpoint = load_checkpoint(checkpoint_file)
+        checkpoint_state = checkpoint["workflow"] if checkpoint is not None else None
+        if checkpoint_state is not None and checkpoint_state.get("status") in TERMINAL:
+            checkpoint_state = None
+
+        source = ".ultra/workflow-state.json"
+        state = live
+        if checkpoint_state is not None:
+            checkpoint_time = newest_time(
+                checkpoint_file, checkpoint_state.get("ts"), checkpoint.get("captured_at")
+            )
+            live_time = newest_time(state_file, live.get("ts")) if live is not None else None
+            if live_time is None or checkpoint_time >= live_time:
+                state = checkpoint_state
+                source = ".ultra/runtime/checkpoint.json"
+                restore_state(state_file, state)
+        if state is None:
             break
         text = (
             "[Ultra workflow resumed] "
             f"command={state.get('command', 'unknown')}; "
             f"task={state.get('task_id', state.get('task', 'unknown'))}; "
             f"step={state.get('step', 'unknown')}; status={state.get('status', 'active')}. "
-            "Continue from .ultra/workflow-state.json and verify state through .ultra/state.db."
+            f"source={source}. Continue from the recovered workflow boundary and verify "
+            "task/session/change state through .ultra/state.db."
         )
         event = data.get("hook_event_name", "SessionStart")
         if event == "SessionStart":