prizmkit 1.1.99 → 1.1.101

package/bundled/dev-pipeline/tests/test_unified_cli.py

@@ -0,0 +1,1045 @@
+"""Tests for the unified Python CLI architecture skeleton."""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import FrozenInstanceError
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PIPELINE_ROOT = REPO_ROOT / "dev-pipeline"
+CLI_PATH = PIPELINE_ROOT / "cli.py"
+def _python_310_plus() -> str:
+    if sys.version_info >= (3, 10):
+        return sys.executable
+    for executable in ("python3.12", "python3.11", "python3.10"):
+        resolved = shutil.which(executable)
+        if resolved:
+            return resolved
+    return sys.executable
+
+
+PYTHON_310_PLUS = _python_310_plus()
+
+if str(PIPELINE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PIPELINE_ROOT))
+
+
+def run_cli(*args):
+    return subprocess.run(
+        [PYTHON_310_PLUS, str(CLI_PATH), *args],
+        cwd=REPO_ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+
+
+def test_cli_help_exposes_python_runtime_command_groups():
+    result = run_cli("--help")
+
+    assert result.returncode == 0
+    assert "canonical Python runtime CLI" in result.stdout
+    assert "without shell wrappers" in result.stdout
+    for group in [
+        "feature",
+        "bugfix",
+        "refactor",
+        "recovery",
+        "reset",
+        "daemon",
+        "status",
+        "diagnostics",
+    ]:
+        assert group in result.stdout
+    assert "Traceback" not in result.stderr
+
+
+def test_module_entrypoint_help_exposes_same_cli():
+    env = {**os.environ, "PYTHONPATH": str(PIPELINE_ROOT)}
+    result = subprocess.run(
+        [PYTHON_310_PLUS, "-m", "prizmkit_runtime", "--help"],
+        cwd=REPO_ROOT,
+        env=env,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+
+    assert result.returncode == 0
+    assert "canonical Python runtime CLI" in result.stdout
+    assert "diagnostics" in result.stdout
+
+
+def test_invalid_arguments_report_usage_without_traceback():
+    result = run_cli("unknown-command")
+
+    assert result.returncode == 2
+    assert "usage:" in result.stderr
+    assert "invalid choice" in result.stderr
+    assert "Traceback" not in result.stderr
+
+
+def test_python_version_guard_mentions_required_version():
+    from prizmkit_runtime.compat import UnsupportedPythonVersion, ensure_supported_python
+
+    ensure_supported_python((3, 10, 0))
+    ensure_supported_python((3, 11, 1))
+
+    with pytest.raises(UnsupportedPythonVersion) as exc_info:
+        ensure_supported_python((3, 9, 18))
+
+    assert "Python 3.10+" in str(exc_info.value)
+    assert "detected Python 3.9" in str(exc_info.value)
+
+
+def test_runtime_paths_support_framework_source_layout():
+    from prizmkit_runtime.paths import RuntimePaths, resolve_runtime_paths
+
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT)
+
+    assert isinstance(paths, RuntimePaths)
+    assert paths.layout == "framework-source"
+    assert paths.pipeline_root == PIPELINE_ROOT.resolve()
+    assert paths.project_root == REPO_ROOT.resolve()
+    assert paths.prizmkit_dir == REPO_ROOT / ".prizmkit"
+    assert paths.feature_plan == paths.plans_dir / "feature-list.json"
+    assert paths.bugfix_plan == paths.plans_dir / "bug-fix-list.json"
+    assert paths.refactor_plan == paths.plans_dir / "refactor-list.json"
+    assert paths.feature_state_dir == paths.state_dir / "features"
+    assert paths.specs_dir == paths.prizmkit_dir / "specs"
+    assert all(isinstance(value, Path) for value in paths.path_values())
+
+
+def test_runtime_paths_support_installed_layout(tmp_path):
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    installed_pipeline = tmp_path / "project" / ".prizmkit" / "dev-pipeline"
+    installed_pipeline.mkdir(parents=True)
+
+    paths = resolve_runtime_paths(pipeline_root=installed_pipeline)
+
+    assert paths.layout == "installed"
+    assert paths.project_root == tmp_path / "project"
+    assert paths.prizmkit_dir == tmp_path / "project" / ".prizmkit"
+    assert paths.pipeline_root == installed_pipeline.resolve()
+    assert paths.logs_dir == paths.state_dir / "logs"
+
+
+def test_runtime_config_models_environment_and_ai_resolution():
+    from prizmkit_runtime.config import AIClientResolution, RuntimeEnvironment, load_runtime_config
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT)
+    config = load_runtime_config(
+        paths,
+        env={
+            "AI_CLI": "claude",
+            "PRIZMKIT_PLATFORM": "codex",
+            "MODEL": "claude-sonnet-4.6",
+            "PRIZMKIT_EFFORT": "full",
+            "MAX_RETRIES": "5",
+            "PATH": "/usr/bin:/bin",
+        },
+    )
+
+    assert config.max_retries == 5
+    assert config.model == "claude-sonnet-4.6"
+    assert config.effort == "full"
+    assert isinstance(config.environment, RuntimeEnvironment)
+    assert isinstance(config.ai_client, AIClientResolution)
+    assert config.ai_client.command == "claude"
+    assert config.ai_client.platform == "claude"
+    assert config.ai_client.source == "environment:AI_CLI"
+    assert "AI_CLI" in config.ai_client.precedence
+    assert ".prizmkit/config.json:ai_cli" in config.ai_client.precedence
+    assert config.runtime_mode == "python-runtime-canonical"
+
+
+def test_runtime_config_matches_canonical_ai_cli_precedence(tmp_path):
+    from prizmkit_runtime.config import load_runtime_config
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    project = tmp_path / "project"
+    pipeline = project / ".prizmkit" / "dev-pipeline"
+    pipeline.mkdir(parents=True)
+    prizmkit_dir = project / ".prizmkit"
+    (prizmkit_dir / "config.json").write_text(json.dumps({"ai_cli": "config-cbc", "platform": "claude"}), encoding="utf-8")
+    (prizmkit_dir / "manifest.json").write_text(json.dumps({"platform": "codex"}), encoding="utf-8")
+    paths = resolve_runtime_paths(pipeline_root=pipeline)
+
+    config_cli = load_runtime_config(paths, env={"PATH": ""}).ai_client
+    assert config_cli.command == "config-cbc"
+    assert config_cli.platform == "codebuddy"
+    assert config_cli.source == "prizmkit-config:ai_cli"
+
+    (prizmkit_dir / "config.json").write_text(json.dumps({"platform": "claude"}), encoding="utf-8")
+    manifest_platform = load_runtime_config(paths, env={"PATH": ""}).ai_client
+    assert manifest_platform.command is None
+    assert manifest_platform.platform == "codex"
+    assert manifest_platform.source == "unresolved:prizmkit-manifest:platform"
+    assert "codex" in manifest_platform.notes[0]
+
+    (prizmkit_dir / "manifest.json").unlink()
+    (prizmkit_dir / "config.json").write_text("{}", encoding="utf-8")
+    legacy_alias = load_runtime_config(paths, env={"CODEBUDDY_CLI": "custom-cbc", "PATH": ""}).ai_client
+    assert legacy_alias.command == "custom-cbc"
+    assert legacy_alias.platform == "codebuddy"
+    assert legacy_alias.source == "environment:CODEBUDDY_CLI"
+
+
+def test_runtime_config_supplied_env_does_not_leak_ambient_path(tmp_path):
+    from prizmkit_runtime.config import load_runtime_config
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    isolated_pipeline = tmp_path / "project" / ".prizmkit" / "dev-pipeline"
+    isolated_pipeline.mkdir(parents=True)
+    paths = resolve_runtime_paths(pipeline_root=isolated_pipeline)
+    config = load_runtime_config(paths, env={})
+
+    assert config.environment.path_entries == ()
+    assert config.ai_client.command is None
+    assert config.ai_client.source == "unresolved"
+
+
+
+    from prizmkit_runtime.commands import list_runtime_commands
+
+    command_keys = {command.key for command in list_runtime_commands()}
+
+    expected = {
+        ("feature", None, "run"),
+        ("feature", None, "status"),
+        ("feature", None, "unskip"),
+        ("feature", None, "test-cli"),
+        ("feature", None, "describe"),
+        ("bugfix", None, "run"),
+        ("bugfix", None, "status"),
+        ("bugfix", None, "unskip"),
+        ("bugfix", None, "describe"),
+        ("refactor", None, "run"),
+        ("refactor", None, "status"),
+        ("refactor", None, "unskip"),
+        ("refactor", None, "describe"),
+        ("recovery", None, "run"),
+        ("recovery", None, "detect"),
+        ("recovery", None, "describe"),
+        ("reset", "feature", "reset"),
+        ("reset", "bugfix", "reset"),
+        ("reset", "refactor", "reset"),
+        ("reset", None, "describe"),
+        ("status", "feature", "status"),
+        ("status", "bugfix", "status"),
+        ("status", "refactor", "status"),
+        ("status", "all", "status"),
+        ("diagnostics", None, "paths"),
+        ("diagnostics", None, "entrypoints"),
+        ("diagnostics", None, "version"),
+    }
+    for target in ["feature", "bugfix", "refactor"]:
+        for action in ["start", "stop", "status", "logs", "restart", "describe"]:
+            expected.add(("daemon", target, action))
+
+    assert expected.issubset(command_keys)
+
+
+def test_python_runtime_command_output_describes_canonical_boundary():
+    result = run_cli("feature", "describe")
+
+    assert result.returncode == 0
+    assert "Python runtime command contract" in result.stdout
+    assert "canonical PrizmKit Python runtime" in result.stdout
+    assert "current entrypoint" in result.stdout
+    assert "python-runtime-canonical" in result.stdout
+    assert "fully replaces" not in result.stdout.lower()
+    assert "shell runtime remains canonical" not in result.stdout
+
+
+def test_option_first_runtime_arguments_are_forwarded(monkeypatch):
+    from prizmkit_runtime import cli as runtime_cli
+
+    captured = []
+
+    def fake_handle(group, action, *, target=None, paths=None, legacy_args=()):
+        captured.append((group, action, target, legacy_args))
+        return runtime_cli.CommandResult(0, "ok", "ok")
+
+    monkeypatch.setattr(runtime_cli, "ensure_supported_python", lambda: None)
+    monkeypatch.setattr(runtime_cli, "handle_runtime_command", fake_handle)
+
+    assert runtime_cli.main(["recovery", "run", "--dry-run"]) == 0
+    assert captured[-1] == ("recovery", "run", None, ("--dry-run",))
+
+    assert runtime_cli.main(["daemon", "feature", "start", "--mode", "standard"]) == 0
+    assert captured[-1] == ("daemon", "start", "feature", ("--mode", "standard"))
+
+    assert runtime_cli.main(["daemon", "feature", "logs", "--follow"]) == 0
+    assert captured[-1] == ("daemon", "logs", "feature", ("--follow",))
+
+    assert runtime_cli.main(["reset", "feature", "--failed"]) == 0
+    assert captured[-1] == ("reset", "reset", "feature", ("--failed",))
+
+    assert runtime_cli.main(["--project-root", "feature", "feature", "describe"]) == 0
+    assert captured[-1] == ("feature", "describe", None, ())
+
+
+def test_unskip_dispatches_status_updater_not_contract(monkeypatch):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.commands import handle_runtime_command
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    class FakeStatus:
+        return_code = 0
+        stdout = "unskipped\n"
+        stderr = ""
+
+    captured = []
+
+    def fake_run_status_action(family, action, invocation, *, item_id="", project_root=None, **kwargs):
+        captured.append((family.kind, action, invocation.item_id, item_id, project_root))
+        return FakeStatus()
+
+    monkeypatch.setattr(runners, "run_status_action", fake_run_status_action)
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT)
+
+    result = handle_runtime_command("feature", "unskip", paths=paths, legacy_args=("F-005",))
+
+    assert result.exit_code == 0
+    assert result.title == "Python feature unskip"
+    assert "unskipped" in result.render()
+    assert "Python runtime command contract" not in result.render()
+    assert captured == [("feature", "unskip", "F-005", "F-005", REPO_ROOT.resolve())]
+
+
+def test_test_cli_reports_ai_resolution_not_contract(monkeypatch):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.commands import handle_runtime_command
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    class FakeAIClient:
+        command = "claude"
+        platform = "claude"
+        source = "test"
+        notes = ()
+
+    class FakeConfig:
+        ai_client = FakeAIClient()
+        runtime_mode = "python-runtime-canonical"
+        model = "claude-sonnet-4.6"
+
+    monkeypatch.setattr(runners, "load_runtime_config", lambda paths: FakeConfig())
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT)
+
+    result = handle_runtime_command("feature", "test-cli", paths=paths)
+    rendered = result.render()
+
+    assert result.exit_code == 0
+    assert result.title == "Python feature AI CLI test"
+    assert "detected_cli: claude" in rendered
+    assert "Python runtime command contract" not in rendered
+
+
+def test_diagnostics_paths_and_entrypoints_are_standard_library_cli_actions():
+    paths_result = run_cli("diagnostics", "paths")
+    entrypoints_result = run_cli("diagnostics", "entrypoints")
+
+    assert paths_result.returncode == 0
+    assert "Runtime path diagnostics" in paths_result.stdout
+    assert "pipeline_root:" in paths_result.stdout
+    assert entrypoints_result.returncode == 0
+    assert "Python runtime entrypoint inventory" in entrypoints_result.stdout
+    assert "runtime:cli:" in entrypoints_result.stdout
+    assert "run-feature.sh" not in entrypoints_result.stdout
+    assert "generate-bootstrap-prompt.py" in entrypoints_result.stdout
+
+
+def test_interoperability_preserves_existing_utility_mapping():
+    from prizmkit_runtime.interoperability import (
+        UTILITY_ENTRYPOINTS,
+        UTILITY_LIBRARY_ONLY,
+        describe_existing_entrypoint,
+    )
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT)
+    invocation = describe_existing_entrypoint("utility", "generate-bootstrap-prompt", paths=paths)
+
+    assert invocation.script_path == PIPELINE_ROOT / "scripts" / "generate-bootstrap-prompt.py"
+    assert invocation.arguments == ()
+    assert invocation.cwd == paths.project_root
+
+    help_result = subprocess.run(
+        [sys.executable, str(invocation.script_path), "--help"],
+        cwd=REPO_ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+    assert help_result.returncode == 0
+    assert "--feature-list" in help_result.stdout
+
+    actual_scripts = {path.name for path in (PIPELINE_ROOT / "scripts").glob("*.py")}
+    mapped_scripts = {Path(relative_path).name for relative_path in UTILITY_ENTRYPOINTS.values()}
+    explicitly_library_only = set(UTILITY_LIBRARY_ONLY)
+
+    assert actual_scripts == mapped_scripts | explicitly_library_only
+    assert explicitly_library_only == {"continuation.py", "utils.py"}
+    assert "parse-stream-progress.py" in mapped_scripts
+    assert "prizmkit-test-gate.py" in mapped_scripts
+
+
+def test_boundary_dataclasses_are_cohesive_and_frozen():
+    from prizmkit_runtime.gitops import BranchContext, WorktreePolicy
+    from prizmkit_runtime.heartbeat import HeartbeatConfig, HeartbeatState
+    from prizmkit_runtime.paths import resolve_runtime_paths
+    from prizmkit_runtime.processes import ProcessHandle, ProcessSpec
+    from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher
+    from prizmkit_runtime.status import StatusTarget, StatusUpdateRequest, default_status_targets
+
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT)
+    session = AISessionConfig(
+        cli_command="claude",
+        platform="claude",
+        model="claude-sonnet-4.6",
+        prompt_path=paths.state_dir / "prompt.md",
+        cwd=paths.project_root,
+    )
+    process = ProcessSpec(command=("python3", "-m", "prizmkit_runtime"), cwd=paths.project_root)
+    handle = ProcessHandle(pid=1234, spec=process, status="described")
+    heartbeat = HeartbeatConfig(heartbeat_file=paths.state_dir / ".heartbeat")
+    heartbeat_state = HeartbeatState(last_seen_epoch=1.0, stale=False, details="fresh")
+    branch = BranchContext(base_branch="main", working_branch="dev/example", project_root=paths.project_root)
+    policy = WorktreePolicy(use_worktree=True, cleanup_on_success=False, preserve_on_failure=True)
+    targets = default_status_targets(paths)
+    status_target = StatusTarget(kind="feature", plan_path=paths.feature_plan, state_dir=paths.feature_state_dir)
+    status_request = StatusUpdateRequest(target=status_target, action="status")
+
+    assert AISessionLauncher(session).describe().startswith("AI session launch boundary")
+    assert handle.spec == process
+    assert heartbeat_state.details == "fresh"
+    assert branch.project_root == paths.project_root
+    assert policy.preserve_on_failure is True
+    assert targets["feature"].plan_path == paths.feature_plan
+    assert status_request.target == status_target
+
+    with pytest.raises(FrozenInstanceError):
+        session.model = "other"
+    with pytest.raises(FrozenInstanceError):
+        heartbeat.interval_seconds = 10
+
+
+def test_runtime_config_loads_prizmkit_env_and_validates_effort(tmp_path):
+    from prizmkit_runtime.config import load_runtime_config, validate_effort
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    project = tmp_path / "project"
+    pipeline = project / ".prizmkit" / "dev-pipeline"
+    pipeline.mkdir(parents=True)
+    prizmkit_dir = project / ".prizmkit"
+    (prizmkit_dir / ".env").write_text(
+        "AI_CLI=env-claude\nPRIZMKIT_EFFORT=max\nMODEL=env-model\n",
+        encoding="utf-8",
+    )
+    paths = resolve_runtime_paths(pipeline_root=pipeline)
+
+    config = load_runtime_config(paths, env={"PATH": ""})
+
+    assert config.ai_client.command == "env-claude"
+    assert config.ai_client.platform == "claude"
+    assert config.ai_client.source == "environment:AI_CLI"
+    assert config.model == "env-model"
+    assert config.effort_validation.valid is True
+    assert validate_effort("max", "codex").valid is False
+    assert "Codex" in validate_effort("max", "codex").message
+
+
+def test_stream_json_support_detection_matches_provider_rules():
+    from prizmkit_runtime.sessions import detect_stream_json_support
+
+    def help_runner(command):
+        if tuple(command) == ("codex", "exec", "--help"):
+            return "Usage: codex exec --json"
+        if tuple(command) == ("claude", "--help"):
+            return "--output-format stream-json"
+        return ""
+
+    codebuddy = detect_stream_json_support("cbc", "codebuddy", help_runner)
+    codex = detect_stream_json_support("codex", "codex", help_runner)
+    claude = detect_stream_json_support("claude", "claude", help_runner)
+    unsupported = detect_stream_json_support("other", "claude", lambda _cmd: "plain help")
+
+    assert codebuddy.enabled and codebuddy.format == "stream-json"
+    assert codex.enabled and codex.format == "codex-json"
+    assert claude.enabled and claude.format == "stream-json"
+    assert unsupported.enabled is False
+
+
+def test_ai_session_command_builders_match_unix_runtime_snapshot(tmp_path):
+    from prizmkit_runtime.sessions import AISessionConfig, build_ai_session_command
+
+    snapshot = json.loads((REPO_ROOT / "tests" / "fixtures" / "dev-pipeline-behavior-snapshots" / "unix-runtime.json").read_text(encoding="utf-8"))
+    prompt = tmp_path / "prompt.md"
+    prompt.write_text("hello", encoding="utf-8")
+    project = tmp_path / "project"
+    project.mkdir()
+
+    claude = build_ai_session_command(
+        AISessionConfig(
+            cli_command="claude",
+            platform="claude",
+            model="sonnet",
+            prompt_path=prompt,
+            cwd=project,
+            effort="high",
+        )
+    )
+    expected_claude = tuple(snapshot["aiCliCommands"]["claudeCommand"]["argv"])
+    assert claude.argv[1:] == expected_claude
+    assert claude.stdin_text is None
+
+    codex = build_ai_session_command(
+        AISessionConfig(
+            cli_command="codex",
+            platform="codex",
+            model="codex-model",
+            prompt_path=prompt,
+            cwd=project,
+            effort="xhigh",
+            use_stream_json=True,
+        )
+    )
+    expected_prefix = tuple(snapshot["aiCliCommands"]["codexCommand"]["argvPrefix"])
+    assert codex.argv[1 : 1 + len(expected_prefix)] == expected_prefix
+    assert "--cd" in codex.argv
+    assert str(project) in codex.argv
+    assert "--json" in codex.argv
+    effort_index = codex.argv.index("model_reasoning_effort=xhigh")
+    assert codex.argv[effort_index - 1] == "--config"
+    assert codex.argv[-1] == "-"
+    assert codex.stdin_text == "hello"
+
+    codebuddy = build_ai_session_command(
+        AISessionConfig(
+            cli_command="custom-cbc",
+            platform="codebuddy",
+            model="codebuddy-model",
+            prompt_path=prompt,
+            cwd=project,
+            effort="medium",
+        )
+    )
+    expected_codebuddy = tuple(snapshot["aiCliCommands"]["customWrapperCommand"]["argv"])
+    assert codebuddy.argv[1:] == expected_codebuddy
+    assert codebuddy.stdin_text == "hello"
+
+
+def test_progress_parser_adds_required_metadata(tmp_path):
+    import importlib.util
+
+    parser_path = PIPELINE_ROOT / "scripts" / "parse-stream-progress.py"
+    spec = importlib.util.spec_from_file_location("parse_stream_progress", parser_path)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+
+    tracker = module.ProgressTracker()
+    tracker.process_event({"type": "system", "subtype": "init", "session_id": "claude-session", "cwd": str(tmp_path)})
+    tracker.process_event({"type": "assistant", "message": {"content": [{"type": "text", "text": "working"}]}})
+    tracker.process_event({"type": "result", "subtype": "success", "stop_reason": "end_turn", "usage": {"input_tokens": 1}, "result": "done"})
+    tracker.process_event({"type": "error", "error": {"message": "permission denied by user"}})
+    data = tracker.to_dict()
+
+    assert data["event_type_counts"]["system"] == 1
+    assert data["event_type_counts"]["assistant"] == 1
+    assert data["claude_session_id"] == "claude-session"
+    assert data["result_subtype"] == "success"
+    assert data["stop_reason"] == "end_turn"
+    assert data["has_usage"] is True
+    assert data["permission_denial_count"] == 1
+
+
+def test_session_dual_writes_progress_and_recovers_backup(tmp_path):
+    from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher, recover_session_log
+
+    fake_cli = tmp_path / "fake_cli.py"
+    fake_cli.write_text(
+        "#!/usr/bin/env python3\n"
+        "import json, sys\n"
+        "print(json.dumps({'type':'system','subtype':'init','session_id':'s1'}), flush=True)\n"
+        "print(json.dumps({'type':'result','subtype':'success','stop_reason':'end_turn','usage':{'tokens':1},'result':'ok'}), flush=True)\n",
+        encoding="utf-8",
+    )
+    fake_cli.chmod(0o755)
+    prompt = tmp_path / "prompt.md"
+    prompt.write_text("hello", encoding="utf-8")
+    session_log = tmp_path / "state" / "sessions" / "sess-1" / "logs" / "session.log"
+    backup_log = tmp_path / "home" / ".prizmkit" / "session-backups" / "sess-1.log"
+    progress = session_log.with_name("progress.json")
+
+    result = AISessionLauncher(
+        AISessionConfig(
+            cli_command=str(fake_cli),
+            platform="codebuddy",
+            model=None,
+            prompt_path=prompt,
+            cwd=tmp_path,
+            log_path=session_log,
+            backup_log_path=backup_log,
+            progress_path=progress,
+        )
+    ).run()
+
+    assert result.exit_code == 0
+    assert session_log.exists()
+    assert progress.exists()
+    progress_data = json.loads(progress.read_text(encoding="utf-8"))
+    assert progress_data["event_type_counts"]["result"] == 1
+    assert progress_data["claude_session_id"] == "s1"
+    assert progress_data["has_usage"] is True
+    assert result.log_recovery is not None
+
+    second_backup = tmp_path / "backup.log"
+    second_log = tmp_path / "main.log"
+    second_log.write_text("tiny", encoding="utf-8")
+    second_backup.write_text("larger recovered log", encoding="utf-8")
+    recovery = recover_session_log(second_log, second_backup)
+    assert recovery.recovered is True
+    assert recovery.cleaned_backup is True
+    assert not second_backup.exists()
+    assert second_log.read_text(encoding="utf-8") == "larger recovered log"
+
+
+def test_session_final_progress_merge_preserves_tracker_fatal_error(tmp_path):
+    from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher
+
+    fake_cli = tmp_path / "context_cli.py"
+    fake_cli.write_text(
+        "#!/usr/bin/env python3\n"
+        "import json\n"
+        "print(json.dumps({'type':'result','is_error':True,'result':'API Error: Your input exceeds the context window'}), flush=True)\n",
+        encoding="utf-8",
+    )
+    fake_cli.chmod(0o755)
+    prompt = tmp_path / "prompt.md"
+    prompt.write_text("hello", encoding="utf-8")
+    session_log = tmp_path / "state" / "sessions" / "sess-context" / "logs" / "session.log"
+    progress = session_log.with_name("progress.json")
+
+    result = AISessionLauncher(
+        AISessionConfig(
+            cli_command=str(fake_cli),
+            platform="codebuddy",
+            model=None,
+            prompt_path=prompt,
+            cwd=tmp_path,
+            log_path=session_log,
+            progress_path=progress,
+        )
+    ).run()
+
+    progress_data = json.loads(progress.read_text(encoding="utf-8"))
+    assert result.progress_summary.fatal_error_code == "context_overflow"
+    assert result.fatal_error_code == "context_overflow"
+    assert progress_data["fatal_error_code"] == "context_overflow"
+
+
+def test_session_unsets_claudecode_and_merges_stderr_order(tmp_path, monkeypatch):
+    from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher
+
+    fake_cli = tmp_path / "env_cli.py"
+    fake_cli.write_text(
+        "#!/usr/bin/env python3\n"
+        "import os, sys\n"
+        "print('stdout-before', flush=True)\n"
+        "print('claudecode=' + os.environ.get('CLAUDECODE', '<unset>'), flush=True)\n"
+        "print('stderr-after', file=sys.stderr, flush=True)\n",
+        encoding="utf-8",
+    )
+    fake_cli.chmod(0o755)
+    monkeypatch.setenv("CLAUDECODE", "1")
+    prompt = tmp_path / "prompt.md"
+    prompt.write_text("hello", encoding="utf-8")
+    session_log = tmp_path / "state" / "sessions" / "sess-env" / "logs" / "session.log"
+
+    result = AISessionLauncher(
+        AISessionConfig(
+            cli_command=str(fake_cli),
+            platform="codebuddy",
+            model=None,
+            prompt_path=prompt,
+            cwd=tmp_path,
+            log_path=session_log,
+        )
+    ).run()
+
+    text = session_log.read_text(encoding="utf-8")
+    assert result.exit_code == 0
+    assert "claudecode=<unset>" in text
+    assert text.index("stdout-before") < text.index("stderr-after")
+
+
+def test_heartbeat_fatal_error_writes_shell_compatible_markers(tmp_path):
+    from prizmkit_runtime.heartbeat import HeartbeatConfig, HeartbeatMonitor
+    from prizmkit_runtime.processes import ProcessSpec, launch_process
+
+    sleeper = tmp_path / "fatal_sleep.py"
+    sleeper.write_text("import time\ntime.sleep(5)\n", encoding="utf-8")
+    progress = tmp_path / "progress.json"
+    progress.write_text('{"fatal_error_code":"context_overflow"}\n', encoding="utf-8")
+    handle = launch_process(ProcessSpec(command=(sys.executable, str(sleeper)), cwd=tmp_path))
+    monitor = HeartbeatMonitor(
+        handle,
+        HeartbeatConfig(
+            heartbeat_file=tmp_path / "heartbeat.json",
+            session_log=tmp_path / "session.log",
+            progress_file=progress,
+            marker_dir=tmp_path,
+            interval_seconds=0.05,
+            stale_after_seconds=10,
+            kill_after_seconds=10,
+            grace_seconds=0.1,
+        ),
+    )
+    monitor.start()
+    deadline = time.time() + 3
+    while time.time() < deadline and not (tmp_path / "fatal-error.json").exists():
+        time.sleep(0.05)
+    result = monitor.stop()
+
+    fatal = json.loads((tmp_path / "fatal-error.json").read_text(encoding="utf-8"))
+    stale = json.loads((tmp_path / "stale-kill.json").read_text(encoding="utf-8"))
+    assert result.killed is True
+    assert result.reason == "context_overflow"
+    assert fatal["killed_at"].endswith("Z")
+    assert fatal["fatal_error_code"] == "context_overflow"
+    assert stale["reason"] == "context_overflow"
+
+
+
+    from prizmkit_runtime.heartbeat import HeartbeatConfig, write_stale_marker
+    from prizmkit_runtime.processes import ProcessSpec, platform_termination_strategy, run_process_with_capture
+
+    sleeper = tmp_path / "sleep.py"
+    sleeper.write_text("import time\ntime.sleep(5)\n", encoding="utf-8")
+    result = run_process_with_capture(
+        ProcessSpec(command=(sys.executable, str(sleeper)), cwd=tmp_path),
+        timeout_seconds=0.2,
+        grace_seconds=0.1,
+    )
+
+    assert result.timed_out is True
+    assert result.termination is not None
+    assert result.termination.reason == "timeout"
+    assert platform_termination_strategy()
+
+    marker = write_stale_marker(tmp_path, reason="stale_session", stale_seconds=3, threshold=2)
+    marker_data = json.loads(marker.read_text(encoding="utf-8"))
+    assert marker_data["reason"] == "stale_session"
+    assert marker_data["threshold"] == 2
+    assert HeartbeatConfig(heartbeat_file=tmp_path / "heartbeat").interval_seconds == 30
+
+
+def test_git_branch_worktree_plans_preserve_shell_invariants(tmp_path):
+    from prizmkit_runtime.gitops import (
+        BranchContext,
+        GitCommandResult,
+        GitPlanResult,
+        WorktreePolicy,
+        branch_create_plan,
+        branch_ensure_return_plan,
+        branch_merge_plan,
+        branch_save_wip,
+        branch_save_wip_plan,
+        worktree_add_plan,
+    )
+
+    context = BranchContext(base_branch="main", working_branch="dev/example", project_root=tmp_path)
+    create = branch_create_plan(context)
+    merge = branch_merge_plan(context, auto_push=True)
+    save_wip = branch_save_wip_plan(context)
+    ensure = branch_ensure_return_plan(context)
+    worktree = worktree_add_plan(context, WorktreePolicy(True, cleanup_on_success=False, preserve_on_failure=True))
+
+    assert create.name == "branch_create"
+    assert any(command.args[:2] == ("checkout", "-b") for command in create.commands)
+    assert any(command.args[:2] == ("stash", "push") for command in merge.commands)
+    assert any(command.args[:2] == ("merge", "--ff-only") for command in merge.commands)
+    assert any(command.args == ("push",) for command in merge.commands)
+    assert save_wip.never_fails is True
+    assert ensure.never_fails is True
+    assert any(command.args[:2] == ("rebase", "--abort") for command in ensure.commands)
+    assert any(command.args[:2] == ("add", "-A") for command in ensure.commands)
+    assert any(".*/worktrees/**" in " ".join(command.args) for command in save_wip.commands)
+    assert worktree.commands[0].args[:2] == ("worktree", "add")
+
+    allowed_failure_result = GitPlanResult(
+        plan=create,
+        results=(
+            GitCommandResult(create.commands[0].args, 1, "", "missing"),
+            GitCommandResult(create.commands[1].args, 0, "", ""),
+        ),
+    )
+    assert allowed_failure_result.ok is True
+
+    failed_branch_change = GitPlanResult(
+        plan=create,
+        results=(
+            GitCommandResult(create.commands[0].args, 1, "", "missing"),
+            GitCommandResult(create.commands[1].args, 1, "", "bad base"),
+            GitCommandResult(create.commands[2].args, 1, "", "missing branch"),
+        ),
+    )
+    assert failed_branch_change.ok is False
+
+    skipped_wip = branch_save_wip(tmp_path, "dev/example")
+    assert skipped_wip.ok is True
+    assert skipped_wip.results == ()
+
+
+def test_worktree_runtime_context_uses_safe_deterministic_path(tmp_path):
+    from prizmkit_runtime.gitops import BranchContext, WorktreePolicy, worktree_runtime_context
+
+    context = BranchContext(base_branch="main", working_branch="dev/F-001-example", project_root=tmp_path / "repo")
+    policy = WorktreePolicy(
+        use_worktree=True,
+        cleanup_on_success=True,
+        preserve_on_failure=False,
+        worktree_root=tmp_path / "state" / "worktrees",
+    )
+
+    runtime = worktree_runtime_context(context, policy)
+
+    assert runtime.worktree_root == (tmp_path / "state" / "worktrees").resolve()
+    assert runtime.worktree_path == runtime.worktree_root / "dev-F-001-example"
+    assert runtime.sentinel_path == runtime.worktree_path / ".prizmkit-worktree"
+    assert runtime.is_cleanup_path_safe() is True
+
+    unsafe = runtime.__class__(
+        context=context,
+        policy=policy,
+        worktree_root=runtime.worktree_root,
+        worktree_path=tmp_path / "other" / "dev-F-001-example",
+        sentinel_path=tmp_path / "other" / "dev-F-001-example" / ".prizmkit-worktree",
+    )
+    assert unsafe.is_cleanup_path_safe() is False
+
+
+def test_linked_worktree_plans_create_branch_without_checkout_and_cleanup_after_merge(tmp_path):
+    from prizmkit_runtime.gitops import (
+        BranchContext,
+        WorktreePolicy,
+        linked_worktree_setup_plan,
+        worktree_merge_plan,
+        worktree_remove_plan,
+        worktree_runtime_context,
+    )
+
+    context = BranchContext(base_branch="main", working_branch="dev/F-001-example", project_root=tmp_path / "repo")
+    policy = WorktreePolicy(True, cleanup_on_success=True, preserve_on_failure=False, worktree_root=tmp_path / "worktrees")
+    runtime = worktree_runtime_context(context, policy)
+
+    setup = linked_worktree_setup_plan(runtime)
+    merge = worktree_merge_plan(runtime, auto_push=True)
+    remove = worktree_remove_plan(runtime, delete_branch=True)
+
+    assert setup.name == "linked_worktree_setup"
+    assert setup.commands[0].args[:2] == ("rev-parse", "--verify")
+    assert setup.commands[1].args[:4] == ("branch", context.working_branch, context.base_branch,)
+    assert setup.commands[2].args[:2] == ("worktree", "list")
+    assert setup.commands[3].args[:3] == ("worktree", "add", "--checkout")
+    assert all(command.args[0] != "checkout" for command in setup.commands)
+    assert setup.require_one_success == ((0, 1),)
+
+    assert merge.commands[0].args[:2] == ("rebase", context.base_branch)
+    assert merge.commands[1].args == ("merge", "--ff-only", context.working_branch)
+    assert merge.commands[2].args == ("push",)
+    assert remove.commands[0].args[:2] == ("worktree", "remove")
+    assert remove.commands[1].args == ("branch", "-d", context.working_branch)
+
+
+def test_guarded_worktree_removal_refuses_unregistered_or_unsafe_paths(monkeypatch, tmp_path):
+    from prizmkit_runtime.gitops import (
+        BranchContext,
+        GitCommandResult,
+        WorktreePolicy,
+        guarded_worktree_remove,
+        worktree_runtime_context,
+    )
+
+    context = BranchContext(base_branch="main", working_branch="dev/F-001-example", project_root=tmp_path / "repo")
+    runtime = worktree_runtime_context(
+        context,
+        WorktreePolicy(True, cleanup_on_success=True, preserve_on_failure=False, worktree_root=tmp_path / "worktrees"),
+    )
+    runtime.worktree_path.mkdir(parents=True)
+
+    calls = []
+
+    def fake_run(project_root, args):
+        calls.append(tuple(args))
+        if tuple(args)[:2] == ("worktree", "list"):
+            return GitCommandResult(tuple(args), 0, "", "")
+        return GitCommandResult(tuple(args), 0, "", "")
+
+    monkeypatch.setattr("prizmkit_runtime.gitops.run_git_command", fake_run)
+    result = guarded_worktree_remove(runtime, delete_branch=True)
+
+    assert result.ok is False
+    assert result.reason == "missing_worktree_sentinel"
+    assert all(call[:2] != ("worktree", "remove") for call in calls)
+
+    (runtime.sentinel_path).write_text(context.working_branch, encoding="utf-8")
+    calls.clear()
+    result = guarded_worktree_remove(runtime, delete_branch=True)
+
+    assert result.ok is False
+    assert result.reason == "worktree_not_registered"
+    assert all(call[:2] != ("worktree", "remove") for call in calls)
+    calls.clear()
+
+    def registered_run(project_root, args):
+        calls.append(tuple(args))
+        if tuple(args)[:2] == ("worktree", "list"):
+            return GitCommandResult(tuple(args), 0, str(runtime.worktree_path) + " abc [dev/F-001-example]\n", "")
+        return GitCommandResult(tuple(args), 0, "", "")
+
+    monkeypatch.setattr("prizmkit_runtime.gitops.run_git_command", registered_run)
+    result = guarded_worktree_remove(runtime, delete_branch=True)
+
+    assert result.ok is True
+    assert ("worktree", "remove", "--force", str(runtime.worktree_path)) in calls
+    assert ("branch", "-d", context.working_branch) in calls
+
+
+
+def test_git_status_safe_ignores_worktree_support_assets(monkeypatch, tmp_path):
+    from prizmkit_runtime.gitops import HIDDEN_TOOL_WORKTREE_EXCLUDES, git_status_safe
+
+    captured = []
+
+    def fake_run(project_root, args):
+        captured.append(tuple(args))
+        return type("Result", (), {"return_code": 0, "stdout": ""})()
+
+    monkeypatch.setattr("prizmkit_runtime.gitops.run_git_command", fake_run)
+
+    assert git_status_safe(tmp_path) == ""
+    status_args = captured[0]
+    joined = " ".join(status_args)
+    assert ":(top,exclude).prizmkit-worktree" in status_args
+    assert ":(top,exclude).claude" in status_args
+    assert ":(top,exclude).prizmkit/dev-pipeline/scripts" in status_args
+    assert all(exclude in status_args for exclude in HIDDEN_TOOL_WORKTREE_EXCLUDES)
+    assert ".prizmkit-worktree" in joined
+
+
+def _init_temp_repo(repo):
+    repo.mkdir(parents=True, exist_ok=True)
+    subprocess.run(["git", "init", "-b", "main"], cwd=repo, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=repo, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=repo, check=True)
+    (repo / "base.txt").write_text("base\n", encoding="utf-8")
+    subprocess.run(["git", "add", "base.txt"], cwd=repo, check=True)
+    subprocess.run(["git", "commit", "-m", "base"], cwd=repo, check=True, stdout=subprocess.DEVNULL)
+
+
+def test_materialize_worktree_support_assets_copies_ignored_assets_without_retired_shell_sources(tmp_path):
+    from prizmkit_runtime.gitops import (
+        BranchContext,
+        WorktreePolicy,
+        ensure_linked_worktree,
+        guarded_worktree_remove,
+        materialize_worktree_support_assets,
+        worktree_runtime_context,
+    )
+
+    repo = tmp_path / "repo"
+    _init_temp_repo(repo)
+    (repo / ".gitignore").write_text(".claude/\n.prizmkit/\n", encoding="utf-8")
+    subprocess.run(["git", "add", ".gitignore"], cwd=repo, check=True)
+    subprocess.run(["git", "commit", "-m", "ignore support"], cwd=repo, check=True, stdout=subprocess.DEVNULL)
+
+    (repo / ".claude" / "agents").mkdir(parents=True)
+    (repo / ".claude" / "agents" / "prizm-dev-team-dev.md").write_text("dev", encoding="utf-8")
+    (repo / ".prizmkit" / "prizm-docs").mkdir(parents=True)
+    (repo / ".prizmkit" / "prizm-docs" / "root.prizm").write_text("PRIZM_VERSION: 1\n", encoding="utf-8")
+    (repo / ".prizmkit" / "config.json").write_text("{}", encoding="utf-8")
+    (repo / ".prizmkit" / "manifest.json").write_text("{}", encoding="utf-8")
+    (repo / ".prizmkit" / "dev-pipeline" / "scripts").mkdir(parents=True)
+    (repo / ".prizmkit" / "dev-pipeline" / "scripts" / "update-checkpoint.py").write_text("# update", encoding="utf-8")
+    (repo / ".prizmkit" / "dev-pipeline" / "run-feature.sh").write_text("retired", encoding="utf-8")
+
+    runtime = worktree_runtime_context(
+        BranchContext("main", "dev/support-assets", repo),
+        WorktreePolicy(True, cleanup_on_success=True, preserve_on_failure=True, worktree_root=tmp_path / "worktrees"),
+    )
+    setup = ensure_linked_worktree(runtime)
+    assert setup.ok
+    assert not (runtime.worktree_path / ".claude" / "agents" / "prizm-dev-team-dev.md").exists()
+
+    result = materialize_worktree_support_assets(runtime)
+
+    assert result.ok
+    assert (runtime.worktree_path / ".claude" / "agents" / "prizm-dev-team-dev.md").is_file()
+    assert (runtime.worktree_path / ".prizmkit" / "prizm-docs" / "root.prizm").is_file()
+    assert (runtime.worktree_path / ".prizmkit" / "config.json").is_file()
+    assert (runtime.worktree_path / ".prizmkit" / "manifest.json").is_file()
+    assert (runtime.worktree_path / ".prizmkit" / "dev-pipeline" / "scripts" / "update-checkpoint.py").is_file()
+    assert not (runtime.worktree_path / ".prizmkit" / "dev-pipeline" / "run-feature.sh").exists()
+
+    assert guarded_worktree_remove(runtime, delete_branch=False).ok
+
+
+def test_worktree_terminal_failure_wip_commit_preserves_dirty_changes_before_cleanup(tmp_path):
+    from prizmkit_runtime.gitops import (
+        BranchContext,
+        WorktreePolicy,
+        ensure_linked_worktree,
+        guarded_worktree_remove,
+        worktree_runtime_context,
+        worktree_save_wip,
+    )
+
+    repo = tmp_path / "repo"
+    _init_temp_repo(repo)
+    runtime = worktree_runtime_context(
+        BranchContext("main", "dev/crashed-work", repo),
+        WorktreePolicy(True, cleanup_on_success=True, preserve_on_failure=True, worktree_root=tmp_path / "worktrees"),
+    )
+    setup = ensure_linked_worktree(runtime)
+    assert setup.ok
+
+    (runtime.worktree_path / "dirty.txt").write_text("dirty work\n", encoding="utf-8")
+    save = worktree_save_wip(runtime)
+    assert save.ok
+    assert any(result.args and result.args[0] == "commit" and result.return_code == 0 for result in save.results)
+
+    removal = guarded_worktree_remove(runtime, delete_branch=False)
+    assert removal.ok
+    assert not runtime.worktree_path.exists()
+
+    branches = subprocess.run(["git", "branch", "--list", "dev/crashed-work"], cwd=repo, check=True, stdout=subprocess.PIPE, text=True).stdout
+    assert "dev/crashed-work" in branches
+    show = subprocess.run(["git", "show", "dev/crashed-work:dirty.txt"], cwd=repo, check=True, stdout=subprocess.PIPE, text=True).stdout
+    assert show == "dirty work\n"
+
+
+def test_daemon_status_cli_preserves_pure_json_stdout(tmp_path):
+    project = tmp_path / "project"
+    (project / ".prizmkit" / "state" / "features").mkdir(parents=True)
+    result = run_cli("--project-root", str(project), "daemon", "feature", "status")
+
+    assert result.returncode == 1
+    assert json.loads(result.stdout) == {"running": False}
+    assert "Pipeline is not running" in result.stderr
+    assert "Python feature daemon" not in result.stdout
+    assert "Transition command contract" not in result.stdout
+