prizmkit 1.1.130 → 1.1.131

package/bundled/dev-pipeline/prizmkit_runtime/runner_classification.py

@@ -3,16 +3,16 @@
 from __future__ import annotations
 
 import hashlib
-import json
 import subprocess
 from pathlib import Path
 
-from .checkpoint_state import load_checkpoint_state
+from .checkpoint_state import CheckpointState, load_checkpoint_state
 from .gitops import git_status_safe, run_git_command
 from .runner_models import PromptGenerationResult, SessionClassification
 from .sessions import AISessionResult
 
 CONTEXT_OVERFLOW = "context_overflow"
+WORKFLOW_BLOCKED = "workflow_blocked"
 STALL_REASON = "context_overflow_without_git_checkpoint_or_artifact_progress"
 CONTEXT_MARKERS = (
     "context_overflow",
@@ -46,29 +46,39 @@ def classify_session(
     previous_fingerprint: object | None = None,
     previous_no_progress_count: int = 0,
 ) -> SessionClassification:
-    """Classify raw AI session signals with durable success precedence."""
+    """Classify raw AI session signals using semantic checkpoint authority."""
     fingerprint = progress_fingerprint(project_root, prompt)
-    invalid_checkpoint = _invalid_existing_workflow_checkpoint(prompt)
-    if invalid_checkpoint is not None:
+    checkpoint = _workflow_checkpoint(prompt, project_root)
+    if checkpoint is not None and not checkpoint.valid:
         return SessionClassification(
             "crashed",
-            reason=f"invalid_workflow_checkpoint:{invalid_checkpoint.error_code}",
+            reason=f"invalid_workflow_checkpoint:{checkpoint.error_code}",
             progress_fingerprint=fingerprint,
+            checkpoint_state=checkpoint.semantic_snapshot,
         )
-    if _is_terminal_success(result) and _has_completed_workflow_artifact(prompt):
+    if checkpoint is not None and checkpoint.semantic_blocked:
+        return SessionClassification(
+            WORKFLOW_BLOCKED,
+            reason=checkpoint.semantic.blocked_reason or "workflow_blocked",
+            progress_fingerprint=fingerprint,
+            checkpoint_state=checkpoint.semantic_snapshot,
+        )
+    if _is_terminal_success(result) and checkpoint is not None and checkpoint.semantic_complete:
         return SessionClassification(
             "success",
-            reason="terminal_success_with_completed_checkpoint",
+            reason="terminal_success_with_semantic_checkpoint",
             progress_fingerprint=fingerprint,
+            checkpoint_state=checkpoint.semantic_snapshot,
         )
-
-    if _has_late_runtime_error_after_completion(result, prompt):
+    if _has_late_runtime_error_after_completion(result, checkpoint):
         return SessionClassification(
             "success",
-            reason="completed_checkpoint_with_late_runtime_error",
+            reason="semantic_checkpoint_with_late_runtime_error",
             progress_fingerprint=fingerprint,
+            checkpoint_state=checkpoint.semantic_snapshot,
         )
 
+    semantic = checkpoint.semantic_snapshot if checkpoint is not None else {}
     if _is_context_overflow(result):
         no_progress_count = _next_no_progress_count(previous_fingerprint, fingerprint, previous_no_progress_count)
         if no_progress_count >= 2:
@@ -78,6 +88,7 @@ def classify_session(
                 fatal_error_code=result.fatal_error_code or CONTEXT_OVERFLOW,
                 progress_fingerprint=fingerprint,
                 no_progress_count=no_progress_count,
+                checkpoint_state=semantic,
             )
         return SessionClassification(
             CONTEXT_OVERFLOW,
@@ -85,17 +96,37 @@ def classify_session(
             fatal_error_code=result.fatal_error_code or CONTEXT_OVERFLOW,
             progress_fingerprint=fingerprint,
             no_progress_count=no_progress_count,
+            checkpoint_state=semantic,
         )
 
     if result.termination_reason == "stale_session":
-        return SessionClassification("crashed", reason="stale_session", progress_fingerprint=fingerprint)
+        return SessionClassification(
+            "crashed", reason="stale_session", progress_fingerprint=fingerprint, checkpoint_state=semantic
+        )
     if result.timed_out or result.termination_reason == "timeout":
-        return SessionClassification("timed_out", reason="timeout", progress_fingerprint=fingerprint)
+        return SessionClassification(
+            "timed_out", reason="timeout", progress_fingerprint=fingerprint, checkpoint_state=semantic
+        )
     if _is_infra_error(result):
-        return SessionClassification("infra_error", reason="ai_runtime_or_provider_error", progress_fingerprint=fingerprint)
+        return SessionClassification(
+            "infra_error",
+            reason="ai_runtime_or_provider_error",
+            progress_fingerprint=fingerprint,
+            checkpoint_state=semantic,
+        )
     if result.exit_code not in (0, None):
-        return SessionClassification("crashed", reason=f"exit_code={result.exit_code}", progress_fingerprint=fingerprint)
-    return SessionClassification("crashed", reason="no_durable_success", progress_fingerprint=fingerprint)
+        return SessionClassification(
+            "crashed",
+            reason=f"exit_code={result.exit_code}",
+            progress_fingerprint=fingerprint,
+            checkpoint_state=semantic,
+        )
+    reason = "no_semantic_completion"
+    if checkpoint is not None and checkpoint.semantic.error_code:
+        reason = f"{reason}:{checkpoint.semantic.error_code}"
+    return SessionClassification(
+        "crashed", reason=reason, progress_fingerprint=fingerprint, checkpoint_state=semantic
+    )
 
 
 def progress_fingerprint(project_root: Path, prompt: PromptGenerationResult | None = None) -> dict[str, object]:
@@ -107,7 +138,9 @@ def progress_fingerprint(project_root: Path, prompt: PromptGenerationResult | No
     if prompt and prompt.artifact_path and prompt.artifact_path.exists():
         artifact_hash = _hash_tree(prompt.artifact_path)
     if prompt and prompt.checkpoint_path and prompt.checkpoint_path.is_file():
-        checkpoint_cursor = load_checkpoint_state(prompt.checkpoint_path).cursor_signature
+        checkpoint_cursor = load_checkpoint_state(
+            prompt.checkpoint_path, project_root=project_root
+        ).cursor_signature
     return {
         "git_diff_fingerprint": hashlib.sha256(status_text.encode()).hexdigest(),
         "checkpoint_cursor": checkpoint_cursor,
@@ -129,67 +162,51 @@ def _is_terminal_success(result: AISessionResult) -> bool:
 
 def _has_late_runtime_error_after_completion(
     result: AISessionResult,
-    prompt: PromptGenerationResult | None,
+    checkpoint: CheckpointState | None,
 ) -> bool:
-    if not _has_completed_workflow_artifact(prompt):
+    if checkpoint is None or not checkpoint.semantic_complete:
         return False
     return _is_context_overflow(result) or _is_infra_error(result)
 
 
-def _has_completed_workflow_artifact(prompt: PromptGenerationResult | None) -> bool:
+def _workflow_checkpoint(
+    prompt: PromptGenerationResult | None,
+    project_root: Path,
+) -> CheckpointState | None:
     if prompt is None:
-        return False
-    if _invalid_existing_workflow_checkpoint(prompt) is not None:
-        return False
-    if prompt.checkpoint_path and prompt.checkpoint_path.is_file():
-        state = load_checkpoint_state(prompt.checkpoint_path)
-        return state.valid and state.all_completed
-    if prompt.artifact_path and has_completed_artifact_path(prompt.artifact_path):
-        return True
-    return False
+        return None
+    checkpoint = prompt.checkpoint_path
+    if checkpoint is None and prompt.artifact_path is not None:
+        checkpoint = prompt.artifact_path / "workflow-checkpoint.json"
+    if checkpoint is None or not checkpoint.is_file():
+        return None
+    return load_checkpoint_state(checkpoint, project_root=project_root)
 
 
-def has_branch_completion_evidence(project_root: Path, base_branch: str, working_branch: str, artifact_path: Path | None) -> bool:
-    """Return true when a recorded task branch already has completed work to merge."""
-    if not base_branch or not working_branch or not has_completed_artifact_path(artifact_path):
+def has_branch_completion_evidence(
+    project_root: Path,
+    base_branch: str,
+    working_branch: str,
+    artifact_path: Path | None,
+) -> bool:
+    """Return true only when a task branch is ahead and semantically complete."""
+    if not base_branch or not working_branch or not has_completed_artifact_path(artifact_path, project_root):
         return False
     return _has_commit_range(project_root, base_branch, working_branch)
 
 
-def has_completed_artifact_path(artifact_path: Path | None) -> bool:
+def has_completed_artifact_path(
+    artifact_path: Path | None,
+    project_root: Path | None = None,
+) -> bool:
+    """Return whether an artifact directory contains semantic completion proof."""
     if artifact_path is None:
         return False
     checkpoint = artifact_path / "workflow-checkpoint.json"
-    if checkpoint.is_file():
-        state = load_checkpoint_state(checkpoint)
-        return state.valid and state.all_completed
-    return _has_valid_completion_summary(artifact_path / "completion-summary.json")
-
-
-def _has_valid_completion_summary(path: Path) -> bool:
-    """Return whether a completion summary contains usable durable notes."""
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
-        return False
-    if not isinstance(data, dict):
+    if not checkpoint.is_file():
         return False
-    notes = data.get("completion_notes")
-    return isinstance(notes, list) and bool(notes) and all(
-        isinstance(note, str) and note.strip() for note in notes
-    )
-
-
-def _invalid_existing_workflow_checkpoint(prompt: PromptGenerationResult | None):
-    if prompt is None:
-        return None
-    checkpoint = prompt.checkpoint_path
-    if checkpoint is None and prompt.artifact_path is not None:
-        checkpoint = prompt.artifact_path / "workflow-checkpoint.json"
-    if checkpoint is None or not checkpoint.is_file():
-        return None
-    state = load_checkpoint_state(checkpoint)
-    return state if not state.valid else None
+    state = load_checkpoint_state(checkpoint, project_root=project_root)
+    return state.semantic_complete
 
 
 def _next_no_progress_count(previous: object | None, current: object, count: int) -> int:
@@ -213,8 +230,12 @@ def _is_context_overflow(result: AISessionResult) -> bool:
 
 
 def _is_infra_error(result: AISessionResult) -> bool:
-    text = "\n".join([result.progress_summary.terminal_result_text, *result.progress_summary.errors, _tail(result.session_log)]).lower()
-    return bool(result.fatal_error_code and result.fatal_error_code != CONTEXT_OVERFLOW) or any(marker in text for marker in INFRA_MARKERS)
+    text = "\n".join(
+        [result.progress_summary.terminal_result_text, *result.progress_summary.errors, _tail(result.session_log)]
+    ).lower()
+    return bool(result.fatal_error_code and result.fatal_error_code != CONTEXT_OVERFLOW) or any(
+        marker in text for marker in INFRA_MARKERS
+    )
 
 
 def _has_commit_range(project_root: Path, start_ref: str, end_ref: str = "HEAD") -> bool:
@@ -250,8 +271,8 @@ def _hash_tree(path: Path) -> str:
     for child in sorted(path.rglob("*")):
         if child.is_file():
             try:
-                rel = child.relative_to(path).as_posix()
-                digest.update(rel.encode())
+                relative = child.relative_to(path).as_posix()
+                digest.update(relative.encode())
                 digest.update(child.read_bytes())
             except OSError:
                 continue

package/bundled/dev-pipeline/prizmkit_runtime/runner_models.py

@@ -39,7 +39,6 @@ class RunnerEnvironment:
     auto_push: bool = False
     use_worktree: bool = False
     dev_branch: str = ""
-    enable_deploy: bool = False
     verbose: bool = False
     live_output: bool = True
     heartbeat_interval_seconds: int = 30
@@ -56,7 +55,6 @@ class RunnerEnvironment:
             auto_push=_truthy(values.get("AUTO_PUSH")),
             use_worktree=_truthy(values.get("USE_WORKTREE")),
             dev_branch=values.get("DEV_BRANCH", ""),
-            enable_deploy=_truthy(values.get("ENABLE_DEPLOY")),
             verbose=_truthy(values.get("VERBOSE")),
             live_output=not _falsey(values.get("PRIZMKIT_LIVE_OUTPUT")),
             heartbeat_interval_seconds=_int_value(values, "HEARTBEAT_INTERVAL", 30),
@@ -131,6 +129,49 @@ class SessionPaths:
         )
 
 
+@dataclass(frozen=True)
+class SemanticCheckpointState:
+    """Cohesive provider-neutral checkpoint metadata persisted by L4."""
+
+    current_stage: str | None = None
+    next_stage: str | None = None
+    stage_result: str | None = None
+    repair_scope: str | None = None
+    repair_round: int = 0
+    authoritative_evidence_paths: Mapping[str, str | None] = field(default_factory=dict)
+    blocked_reason: str | None = None
+    terminal_status: str | None = None
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, object] | None) -> "SemanticCheckpointState":
+        data = value or {}
+        evidence = data.get("authoritative_evidence_paths")
+        return cls(
+            current_stage=_optional_text(data.get("current_stage")),
+            next_stage=_optional_text(data.get("next_stage")),
+            stage_result=_optional_text(data.get("stage_result")),
+            repair_scope=_optional_text(data.get("repair_scope")),
+            repair_round=max(0, _safe_int(data.get("repair_round"), 0)),
+            authoritative_evidence_paths=(
+                dict(evidence) if isinstance(evidence, Mapping) else {}
+            ),
+            blocked_reason=_optional_text(data.get("blocked_reason")),
+            terminal_status=_optional_text(data.get("terminal_status")),
+        )
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "current_stage": self.current_stage,
+            "next_stage": self.next_stage,
+            "stage_result": self.stage_result,
+            "repair_scope": self.repair_scope,
+            "repair_round": self.repair_round,
+            "authoritative_evidence_paths": dict(self.authoritative_evidence_paths),
+            "blocked_reason": self.blocked_reason,
+            "terminal_status": self.terminal_status,
+        }
+
+
 @dataclass(frozen=True)
 class ContinuationState:
     """Provider-neutral durable handoff inputs for the next AI session."""
@@ -150,6 +191,7 @@ class ContinuationState:
     active_dev_branch: str = ""
     base_branch: str = ""
     fatal_error_code: str = ""
+    checkpoint_state: SemanticCheckpointState = field(default_factory=SemanticCheckpointState)
 
 
 @dataclass(frozen=True)
@@ -161,6 +203,7 @@ class SessionClassification:
     fatal_error_code: str = ""
     progress_fingerprint: Mapping[str, object] = field(default_factory=dict)
     no_progress_count: int = 0
+    checkpoint_state: Mapping[str, object] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)
@@ -336,7 +379,14 @@ def _falsey(value: str | None) -> bool:
     return str(value or "").strip().lower() in {"0", "false", "no", "off"}
 
 
-def _safe_int(value: str | None, default: int) -> int:
+def _optional_text(value: object) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _safe_int(value: object, default: int) -> int:
     try:
         return int(str(value))
     except (TypeError, ValueError):

package/bundled/dev-pipeline/prizmkit_runtime/runner_recovery.py

@@ -9,6 +9,7 @@ import time
 from dataclasses import dataclass
 from pathlib import Path
 
+from .checkpoint_state import load_checkpoint_state
 from .config import load_runtime_config
 from .paths import RuntimePaths
 from .runner_models import RunnerEnvironment, SessionPaths
@@ -148,12 +149,26 @@ def run_recovery(paths: RuntimePaths, legacy_args: tuple[str, ...] = ()) -> tupl
         )
     )
     result = launcher.run()
-    outcome = _recovery_outcome(paths.project_root, result.exit_code)
+    checkpoint_path = _recovery_checkpoint_path(paths.project_root, detection)
+    outcome, semantic = _recovery_outcome(
+        paths.project_root,
+        result.exit_code,
+        checkpoint_path=checkpoint_path,
+    )
     session_paths.session_status_json.write_text(
-        json.dumps({"session_id": session_id, "outcome": outcome}, indent=2) + "\n",
+        json.dumps(
+            {
+                "session_id": session_id,
+                "outcome": outcome,
+                "checkpoint_path": str(checkpoint_path) if checkpoint_path else None,
+                "checkpoint_state": semantic,
+            },
+            indent=2,
+        )
+        + "\n",
         encoding="utf-8",
     )
-    return 0 if outcome in {"success", "success_wip", "no_changes"} else 1, outcome + "\n", ""
+    return 0 if outcome in {"success", "no_changes"} else 1, outcome + "\n", ""
 
 
 def _option_value(args: tuple[str, ...], flag: str) -> str | None:
@@ -165,16 +180,40 @@ def _option_value(args: tuple[str, ...], flag: str) -> str | None:
     return None
 
 
-def _recovery_outcome(project_root: Path, exit_code: int | None) -> str:
-    commits = subprocess.run(
-        ["git", "-C", str(project_root), "rev-list", "--count", "HEAD", "^main"],
-        stdout=subprocess.PIPE,
-        stderr=subprocess.DEVNULL,
-        text=True,
-        check=False,
-    )
-    if commits.returncode == 0 and commits.stdout.strip() not in {"", "0"}:
-        return "success"
+def _recovery_checkpoint_path(project_root: Path, detection: dict[str, object]) -> Path | None:
+    """Select the L4 checkpoint identified by recovery inspection."""
+    semantic = detection.get("semantic_checkpoint")
+    if isinstance(semantic, dict) and semantic.get("path"):
+        candidate = project_root / str(semantic["path"])
+        if candidate.is_file():
+            return candidate
+    execution_owner = detection.get("execution_owner")
+    checkpoints = execution_owner.get("l4_checkpoints") if isinstance(execution_owner, dict) else []
+    if isinstance(checkpoints, list) and len(checkpoints) == 1:
+        candidate = project_root / str(checkpoints[0])
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _recovery_outcome(
+    project_root: Path,
+    exit_code: int | None,
+    *,
+    checkpoint_path: Path | None = None,
+) -> tuple[str, dict[str, object]]:
+    """Classify recovery from semantic L4 state without mutating partial work."""
+    if checkpoint_path is not None:
+        state = load_checkpoint_state(checkpoint_path, project_root=project_root)
+        semantic = state.semantic_snapshot
+        if state.valid and state.semantic_complete:
+            return "success", semantic
+        if state.valid and state.semantic_blocked:
+            return "workflow_blocked", semantic
+        if state.exists and not state.valid:
+            return "blocked_invalid_checkpoint", semantic
+        return "partial" if exit_code == 0 else "failed", semantic
+
     status = subprocess.run(
         ["git", "-C", str(project_root), "status", "--porcelain"],
         stdout=subprocess.PIPE,
@@ -183,15 +222,6 @@ def _recovery_outcome(project_root: Path, exit_code: int | None) -> str:
         check=False,
     )
     has_changes = bool(status.stdout.strip())
-    if exit_code == 0 and has_changes:
-        subprocess.run(["git", "-C", str(project_root), "add", "-A"], check=False)
-        subprocess.run(
-            ["git", "-C", str(project_root), "commit", "--no-verify", "-m", "chore: save recovery work"],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
-        return "success_wip"
-    if exit_code == 0:
-        return "no_changes"
-    return "partial" if has_changes else "failed"
+    if exit_code == 0 and not has_changes:
+        return "no_changes", {}
+    return ("partial" if has_changes else "failed"), {}

package/bundled/dev-pipeline/prizmkit_runtime/runner_status.py

@@ -51,6 +51,7 @@ def run_status_action(
     continuation_summary_path: Path | None = None,
     no_progress_count: int | None = None,
     progress_fingerprint: object | None = None,
+    checkpoint_state: object | None = None,
     project_root: Path | None = None,
 ) -> StatusCommandResult:
     max_retries = _resolved_max_retries(invocation) if max_retries is None else max(0, max_retries)
@@ -88,6 +89,8 @@ def run_status_action(
         command.extend(["--no-progress-count", str(no_progress_count)])
     if progress_fingerprint is not None:
         command.extend(["--progress-fingerprint", json.dumps(progress_fingerprint, sort_keys=True)])
+    if checkpoint_state is not None:
+        command.extend(["--checkpoint-state", json.dumps(checkpoint_state, sort_keys=True)])
     if project_root is not None:
         command.extend(["--project-root", str(project_root)])
 
@@ -146,6 +149,7 @@ def update_item(
         continuation_summary_path=metadata.get("continuation_summary_path") if isinstance(metadata.get("continuation_summary_path"), Path) else None,
         no_progress_count=metadata.get("no_progress_count") if isinstance(metadata.get("no_progress_count"), int) else None,
         progress_fingerprint=metadata.get("progress_fingerprint"),
+        checkpoint_state=metadata.get("checkpoint_state"),
     )
 
 

package/bundled/dev-pipeline/prizmkit_runtime/runners.py

@@ -621,6 +621,15 @@ def _process_item_locked(
                     "max_infra_retries": invocation.max_infra_retries,
                     "no_progress_count": previous_no_progress_count,
                     "progress_fingerprint": previous_fingerprint or {},
+                    "checkpoint_state": {
+                        key: metadata.get(key)
+                        for key in (
+                            "current_stage", "next_stage", "stage_result",
+                            "repair_scope", "repair_round",
+                            "authoritative_evidence_paths", "blocked_reason",
+                            "terminal_status",
+                        )
+                    },
                     "task_type": family.task_type,
                     "active_dev_branch": branch_name,
                     "base_branch": base_branch,
@@ -691,6 +700,7 @@ def _process_item_locked(
                 worktree_path=worktree_runtime.worktree_path if worktree_runtime is not None else None,
                 reason=classification.reason,
                 fatal_error_code=classification.fatal_error_code,
+                checkpoint_state=classification.checkpoint_state,
             )
 
             update = update_item(
@@ -706,6 +716,7 @@ def _process_item_locked(
                 continuation_summary_path=summary_path,
                 no_progress_count=classification.no_progress_count,
                 progress_fingerprint=classification.progress_fingerprint,
+                checkpoint_state=classification.checkpoint_state,
             )
             if not update.ok:
                 raise RuntimeError(update.text)
@@ -767,7 +778,7 @@ def _process_item_locked(
 
 def _is_retryable_ai_outcome(session_status: str, new_status: str) -> bool:
     """Return whether a persisted post-launch outcome should continue in-process."""
-    if session_status == "success" or session_status == "stalled_context_continuation":
+    if session_status in {"success", "stalled_context_continuation", "workflow_blocked"}:
         return False
     return new_status in {"in_progress", "pending"} and session_status in {
         "context_overflow",
@@ -1079,6 +1090,7 @@ def _write_session_status(
     worktree_path: Path | None = None,
     reason: str = "",
     fatal_error_code: str = "",
+    checkpoint_state: object | None = None,
 ) -> None:
     payload = {
         "status": status,
@@ -1094,6 +1106,8 @@ def _write_session_status(
         payload["reason"] = reason
     if fatal_error_code:
         payload["fatal_error_code"] = fatal_error_code
+    if isinstance(checkpoint_state, dict):
+        payload["checkpoint_state"] = checkpoint_state
     session_paths.session_status_json.parent.mkdir(parents=True, exist_ok=True)
     session_paths.session_status_json.write_text(
         json.dumps(payload, indent=2, sort_keys=True) + "\n",