prizmkit 1.1.100 → 1.1.102

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

@@ -0,0 +1,1226 @@
+"""Parity-focused tests for Python foreground runner helpers."""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PIPELINE_ROOT = REPO_ROOT / "dev-pipeline"
+CLI_PATH = PIPELINE_ROOT / "cli.py"
+
+if str(PIPELINE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PIPELINE_ROOT))
+
+
+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()
+UNIX_RUNTIME_SNAPSHOT = REPO_ROOT / "tests" / "fixtures" / "dev-pipeline-behavior-snapshots" / "unix-runtime.json"
+
+
+def _load_unix_runtime_snapshot():
+    return json.loads(UNIX_RUNTIME_SNAPSHOT.read_text(encoding="utf-8"))
+
+
+def _make_paths(tmp_path):
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    project = tmp_path / "project"
+    (project / ".prizmkit" / "plans").mkdir(parents=True)
+    return resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=project)
+
+
+def _write_feature_list(paths):
+    paths.feature_plan.write_text(
+        json.dumps(
+            {
+                "$schema": "dev-pipeline-feature-list-v1",
+                "project_name": "Fake",
+                "features": [
+                    {"id": "F-001", "title": "Low", "status": "pending", "priority": "low", "dependencies": []},
+                    {"id": "F-002", "title": "Critical", "status": "pending", "priority": "critical", "dependencies": []},
+                    {"id": "F-003", "title": "Blocked", "status": "pending", "priority": "high", "dependencies": ["F-001"]},
+                ],
+            }
+        ),
+        encoding="utf-8",
+    )
+
+
+def test_retired_shell_runtime_files_are_absent_from_source():
+    retired = [
+        "run-feature.sh",
+        "run-bugfix.sh",
+        "run-refactor.sh",
+        "run-recovery.sh",
+        "launch-feature-daemon.sh",
+        "launch-bugfix-daemon.sh",
+        "launch-refactor-daemon.sh",
+        "reset-feature.sh",
+        "reset-bug.sh",
+        "reset-refactor.sh",
+        "lib/branch.sh",
+        "lib/common.sh",
+        "lib/heartbeat.sh",
+    ]
+
+    for relative_path in retired:
+        assert not (PIPELINE_ROOT / relative_path).exists(), relative_path
+
+
+def test_python_parity_suite_declares_coverage_for_all_legacy_unix_snapshot_scenarios():
+    """Keep the F-011 snapshot as an explicit oracle without reviving shell sources."""
+    snapshot = _load_unix_runtime_snapshot()
+    suite_text = "\n".join(
+        [
+            Path(__file__).read_text(encoding="utf-8"),
+            (PIPELINE_ROOT / "tests" / "test_unified_cli.py").read_text(encoding="utf-8"),
+            (PIPELINE_ROOT / "tests" / "test_auto_skip.py").read_text(encoding="utf-8"),
+        ]
+    )
+    coverage_tokens = {
+        "entrypointContracts": {
+            "runnerHelpContracts": ["test_cli_help_exposes_python_runtime_command_groups"],
+            "runnerMissingListErrors": ["test_python_runner_missing_list_errors_match_snapshot_contract"],
+            "recoveryHelpContract": ["test_python_entrypoint_contracts_match_snapshot_contracts"],
+            "resetHelpContracts": ["test_python_entrypoint_contracts_match_snapshot_contracts"],
+            "daemonStatusContracts": ["test_python_entrypoint_contracts_match_snapshot_contracts"],
+        },
+        "envResolution": {
+            "verboseAndStreamJson": ["test_python_env_resolution_scenarios_match_snapshot_contracts"],
+            "effortModelAndCli": ["test_ai_session_command_builders_match_unix_runtime_snapshot"],
+            "worktreeIgnored": ["test_runner_environment_enables_worktree_by_default_and_accepts_falsey_opt_out"],
+            "autoPushFlag": ["test_successful_worktree_session_merges_cleans_branch_and_honors_auto_push"],
+        },
+        "aiCliCommands": {
+            "claudeCommand": ["test_ai_session_command_builders_match_unix_runtime_snapshot"],
+            "codexCommand": ["test_ai_session_command_builders_match_unix_runtime_snapshot"],
+            "customWrapperCommand": ["test_ai_session_command_builders_match_unix_runtime_snapshot"],
+        },
+        "fakeCliOutcomes": {
+            "success": ["test_session_dual_writes_progress_and_recovers_backup"],
+            "contextOverflowContinuation": ["test_context_overflow_reuses_worktree_and_skips_cleanup_until_terminal_outcome"],
+            "infraErrorRetry": ["test_status_updater_behavior_matches_unix_runtime_snapshot"],
+            "crashFailure": ["test_status_updater_behavior_matches_unix_runtime_snapshot"],
+            "timeoutStaleKill": ["test_heartbeat_fatal_error_writes_shell_compatible_markers"],
+        },
+        "artifactShapes": {
+            "sessionLogsAndProgress": ["test_session_dual_writes_progress_and_recovers_backup"],
+            "homeBackupNormalization": ["test_session_dual_writes_progress_and_recovers_backup"],
+        },
+        "resetBehavior": {
+            "manualResetWarningOrder": ["test_python_reset_warns_before_mutation_and_matches_snapshot_cleanup"],
+            "cleanResetDeletesContinuationArtifacts": ["test_python_clean_reset_deletes_continuation_artifacts_for_all_families"],
+        },
+        "daemonBehavior": {
+            "stalePidStatusByTaskType": ["test_python_daemon_stale_pid_matches_snapshot"],
+            "controlledStartStop": ["test_python_daemon_controlled_start_status_stop_matches_snapshot"],
+        },
+        "continuationBehavior": {
+            "noProgressStall": ["test_status_updater_behavior_matches_unix_runtime_snapshot"],
+            "branchAndArtifactReuse": ["test_context_overflow_reuses_worktree_and_skips_cleanup_until_terminal_outcome"],
+        },
+        "statusUpdaterBehavior": {
+            "contextOverflowMetadata": ["test_status_updater_behavior_matches_unix_runtime_snapshot"],
+            "infraErrorRetryBudget": ["test_status_updater_behavior_matches_unix_runtime_snapshot"],
+            "crashFailureBudget": ["test_status_updater_behavior_matches_unix_runtime_snapshot"],
+            "resetCleanMetadataCleanup": ["test_status_updater_behavior_matches_unix_runtime_snapshot"],
+            "noProgressStall": ["test_status_updater_behavior_matches_unix_runtime_snapshot"],
+        },
+    }
+
+    assert set(coverage_tokens) == set(snapshot["requiredScenarios"])
+    for section, scenario_names in snapshot["requiredScenarios"].items():
+        assert set(coverage_tokens[section]) == set(scenario_names), section
+        for scenario_name, tokens in coverage_tokens[section].items():
+            assert tokens, f"{section}.{scenario_name} has no coverage tokens"
+            for token in tokens:
+                assert token in suite_text, f"{section}.{scenario_name} coverage token missing: {token}"
+
+
+def test_python_runner_missing_list_errors_match_snapshot_contract(tmp_path):
+    from prizmkit_runtime.runners import run_pipeline_command
+
+    snapshot = _load_unix_runtime_snapshot()["entrypointContracts"]["runnerMissingListErrors"]
+    for kind in ("feature", "bugfix", "refactor"):
+        paths = _make_paths(tmp_path / f"missing-{kind}")
+        result = run_pipeline_command(kind, "run", (), paths)
+
+        assert result.exit_code == snapshot[kind]["exitCode"]
+        assert "Plan list not found" in result.render()
+
+
+def test_python_entrypoint_contracts_match_snapshot_contracts(tmp_path):
+    from prizmkit_runtime.commands import handle_runtime_command
+    from prizmkit_runtime.daemon import run_daemon_command
+    from prizmkit_runtime.paths import resolve_runtime_paths
+    from prizmkit_runtime.reset import run_reset_command
+
+    snapshot = _load_unix_runtime_snapshot()["entrypointContracts"]
+    paths = _make_paths(tmp_path / "entrypoints")
+
+    recovery = handle_runtime_command("recovery", "describe", paths=paths)
+    assert recovery.exit_code == snapshot["recoveryHelpContract"]["exitCode"]
+    assert "Python runtime command contract" in recovery.render()
+    assert "recovery describe" in recovery.render()
+
+    for kind in ("feature", "bugfix", "refactor"):
+        reset = run_reset_command(kind, ("--help",), paths)
+        assert reset.exit_code == snapshot["resetHelpContracts"][kind]["exitCode"]
+        assert "Usage: prizmkit-runtime reset" in reset.render()
+
+        daemon_paths = resolve_runtime_paths(
+            pipeline_root=PIPELINE_ROOT,
+            project_root=tmp_path / "daemon-status" / kind,
+        )
+        daemon = run_daemon_command(kind, "status", (), daemon_paths)
+        payload = json.loads(daemon.render())
+        assert daemon.exit_code == snapshot["daemonStatusContracts"][kind]["exitCode"]
+        assert payload["running"] is False
+
+
+def test_python_env_resolution_scenarios_match_snapshot_contracts(tmp_path):
+    from prizmkit_runtime.sessions import AISessionConfig, build_ai_session_command, detect_stream_json_support
+
+    snapshot = _load_unix_runtime_snapshot()["envResolution"]
+    prompt = tmp_path / "prompt.md"
+    prompt.write_text("hello", encoding="utf-8")
+
+    claude = build_ai_session_command(
+        AISessionConfig(
+            cli_command="claude",
+            platform="claude",
+            model=None,
+            prompt_path=prompt,
+            cwd=tmp_path,
+            verbose=True,
+        )
+    )
+    assert ("--verbose" in claude.argv) is snapshot["verboseAndStreamJson"]["claudeVerboseHasFlag"]
+
+    codebuddy = build_ai_session_command(
+        AISessionConfig(
+            cli_command="cbc",
+            platform="codebuddy",
+            model=None,
+            prompt_path=prompt,
+            cwd=tmp_path,
+            use_stream_json=True,
+        )
+    )
+    assert ("--output-format" in codebuddy.argv and "stream-json" in codebuddy.argv) is snapshot["verboseAndStreamJson"]["codebuddyStreamJsonHasFlag"]
+
+    codex_support = detect_stream_json_support("codex", "codex", lambda command: "Usage: codex exec --json")
+    assert codex_support.enabled is True
+    assert codex_support.format == "codex-json"
+
+
+def test_windows_structural_paths_use_installed_python_runtime_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.pipeline_root == installed_pipeline.resolve()
+    assert all("dev-pipeline-windows" not in str(value) for value in paths.path_values())
+    assert all(not str(value).endswith(".ps1") for value in paths.path_values())
+
+
+def test_windows_process_tree_termination_strategy_is_taskkill_backed_without_powershell(monkeypatch, tmp_path):
+    from prizmkit_runtime import processes
+    from prizmkit_runtime.processes import ProcessHandle, ProcessSpec
+
+    calls = []
+
+    class FakeCompleted:
+        returncode = 0
+        stdout = ""
+        stderr = ""
+
+    def fake_run(command, **kwargs):
+        calls.append((tuple(command), kwargs))
+        return FakeCompleted()
+
+    monkeypatch.setattr(processes.os, "name", "nt")
+    monkeypatch.setattr(processes.subprocess, "CREATE_NEW_PROCESS_GROUP", 0x200, raising=False)
+    monkeypatch.setattr(processes.subprocess, "run", fake_run)
+
+    spec = ProcessSpec(command=(sys.executable, "-c", "pass"), cwd=tmp_path)
+    handle = ProcessHandle(pid=1234, spec=spec, status="running", popen=None)
+    launched_flags = processes._creationflags_for_platform(True)
+    handle_result = processes.terminate_process_tree(handle, "test-timeout", grace_seconds=0)
+
+    assert launched_flags == 0x200
+    assert processes.platform_termination_strategy() == ("CREATE_NEW_PROCESS_GROUP", "taskkill /PID <pid> /T /F")
+    assert handle_result.terminated is True
+    assert handle_result.forced is True
+    assert calls[-1][0] == ("taskkill", "/PID", "1234", "/T", "/F")
+
+    calls.clear()
+    monkeypatch.setattr(processes, "is_pid_running", lambda pid: True)
+    pid_result = processes.terminate_pid_tree(5678, "daemon-stop", grace_seconds=0)
+
+    assert pid_result.terminated is True
+    assert pid_result.forced is True
+    assert calls[-1][0] == ("taskkill", "/PID", "5678", "/T", "/F")
+
+
+def test_runner_models_parse_legacy_args_and_environment(tmp_path):
+    from prizmkit_runtime.runner_models import RunnerEnvironment, family_for, parse_invocation
+
+    paths = _make_paths(tmp_path)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(
+        family,
+        "run",
+        ("custom-list.json", "F-2", "--features", "F-003:F-001", "--max-retries", "7", "--max-infra-retries=5", "--mode", "full", "--critic"),
+    )
+    env = RunnerEnvironment.from_env(
+        {
+            "STOP_ON_FAILURE": "1",
+            "AUTO_PUSH": "true",
+            "DEV_BRANCH": "dev/custom",
+            "VERBOSE": "1",
+            "STALE_KILL_THRESHOLD": "9",
+            "MAX_RETRIES": "9",
+            "STRICT_BEHAVIOR_CHECK": "false",
+        }
+    )
+
+    assert invocation.list_path == Path("custom-list.json")
+    assert invocation.item_id == "F-002"
+    assert invocation.item_filter == "F-003:F-001"
+    assert invocation.max_retries == 7
+    assert invocation.max_infra_retries == 5
+    assert invocation.mode == "full"
+    assert invocation.critic is True
+    assert env.stop_on_failure is True
+    assert env.auto_push is True
+    assert env.dev_branch == "dev/custom"
+    assert env.stale_kill_threshold_seconds == 9
+    assert env.max_retries == 9
+    assert env.strict_behavior_check is False
+
+
+def test_runner_environment_enables_worktree_by_default_and_accepts_falsey_opt_out():
+    from prizmkit_runtime.runner_models import RunnerEnvironment
+
+    assert RunnerEnvironment.from_env({}).use_worktree is True
+    assert RunnerEnvironment.from_env({"USE_WORKTREE": "1"}).use_worktree is True
+    assert RunnerEnvironment.from_env({"USE_WORKTREE": "true"}).use_worktree is True
+    assert RunnerEnvironment.from_env({"USE_WORKTREE": "unexpected"}).use_worktree is True
+
+    for falsey in ("0", "false", "no", "off"):
+        assert RunnerEnvironment.from_env({"USE_WORKTREE": falsey}).use_worktree is False
+
+
+def test_status_bridge_preserves_feature_filter_selection(tmp_path):
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+    from prizmkit_runtime.runner_status import get_next, start_item, update_item
+
+    paths = _make_paths(tmp_path)
+    _write_feature_list(paths)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(family, "run", ("--features", "F-002:F-003"))
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+
+    next_result = get_next(family, invocation, paths.project_root)
+    assert next_result.ok
+    assert isinstance(next_result.data, dict)
+    assert next_result.data["feature_id"] == "F-002"
+
+    start = start_item(family, invocation, "F-002", paths.project_root)
+    assert start.ok
+    assert start.data["new_status"] == "in_progress"
+
+    update = update_item(family, invocation, "F-002", "context_overflow", "F-002-session", paths.project_root, active_dev_branch="dev/F-002", base_branch="main", no_progress_count=0, progress_fingerprint={"head_commit": "abc"})
+    assert update.ok
+    assert update.data["new_status"] == "in_progress"
+    assert update.data["restart_policy"] == "context_overflow_continuation"
+    assert update.data["context_overflow_count"] == 1
+
+
+def test_status_bridge_passes_max_retries_from_invocation_or_environment(monkeypatch, tmp_path):
+    import subprocess
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+    from prizmkit_runtime.runner_status import status_text
+
+    paths = _make_paths(tmp_path)
+    family = family_for("feature", paths)
+    explicit = parse_invocation(family, "run", ("--max-retries", "8"))
+    explicit = explicit.__class__(**{**explicit.__dict__, "list_path": paths.feature_plan})
+    fallback = parse_invocation(family, "run", ())
+    fallback = fallback.__class__(**{**fallback.__dict__, "list_path": paths.feature_plan})
+    calls = []
+
+    def fake_run(command, **kwargs):
+        calls.append(tuple(command))
+        return subprocess.CompletedProcess(command, 0, stdout="PIPELINE_COMPLETE\n", stderr="")
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+    monkeypatch.setenv("MAX_RETRIES", "6")
+
+    status_text(family, explicit, paths.project_root)
+    status_text(family, fallback, paths.project_root)
+
+    first = calls[0]
+    second = calls[1]
+    assert first[first.index("--max-retries") + 1] == "8"
+    assert second[second.index("--max-retries") + 1] == "6"
+
+
+def test_stop_on_failure_does_not_stop_on_retryable_pending(monkeypatch, tmp_path):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    paths = _make_paths(tmp_path)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+    queue = [
+        SimpleNamespace(ok=True, stdout=json.dumps({"feature_id": "F-001"}), data={"feature_id": "F-001"}, text=""),
+        SimpleNamespace(ok=True, stdout=json.dumps({"feature_id": "F-002"}), data={"feature_id": "F-002"}, text=""),
+        SimpleNamespace(ok=True, stdout="PIPELINE_COMPLETE\n", data=None, text="PIPELINE_COMPLETE"),
+    ]
+    processed = []
+
+    monkeypatch.setenv("STOP_ON_FAILURE", "1")
+    monkeypatch.setattr(runners, "get_next", lambda *args, **kwargs: queue.pop(0))
+
+    def fake_process(_family, _invocation, item_id, _paths, *, initial_metadata):
+        processed.append(item_id)
+        return "pending" if item_id == "F-001" else "completed"
+
+    monkeypatch.setattr(runners, "_process_item", fake_process)
+
+    result = runners._run_pipeline(family, invocation, paths)
+
+    assert processed == ["F-001", "F-002"]
+    assert result.completed is True
+    assert result.stopped_reason == "pipeline_complete"
+    assert result.details == ("F-001:pending", "F-002:completed")
+
+
+def test_stop_on_failure_still_stops_on_terminal_status(monkeypatch, tmp_path):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    paths = _make_paths(tmp_path)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+
+    monkeypatch.setenv("STOP_ON_FAILURE", "1")
+    monkeypatch.setattr(
+        runners,
+        "get_next",
+        lambda *args, **kwargs: SimpleNamespace(ok=True, stdout=json.dumps({"feature_id": "F-001"}), data={"feature_id": "F-001"}, text=""),
+    )
+    monkeypatch.setattr(runners, "_process_item", lambda *args, **kwargs: "failed")
+
+    result = runners._run_pipeline(family, invocation, paths)
+
+    assert result.completed is False
+    assert result.stopped_reason == "stop_on_failure"
+    assert result.last_status == "failed"
+
+
+def test_prompt_generation_result_preserves_per_item_model(monkeypatch, tmp_path):
+    from prizmkit_runtime.runner_models import SessionPaths, family_for, parse_invocation
+    from prizmkit_runtime.runner_prompts import generate_prompt
+
+    paths = _make_paths(tmp_path)
+    family = family_for("bugfix", paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.bugfix_plan})
+    session_paths = SessionPaths.for_item(paths.bugfix_state_dir, "B-001", "B-001-session")
+
+    def fake_run(command, **kwargs):
+        assert str(family.prompt_script) in command
+        assert "--bug-id" in command
+        return subprocess.CompletedProcess(
+            command,
+            0,
+            stdout=json.dumps(
+                {
+                    "success": True,
+                    "output_path": str(session_paths.prompt_path),
+                    "checkpoint_path": str(paths.project_root / ".prizmkit" / "bugfix" / "B-001" / "workflow-checkpoint.json"),
+                    "model": "per-item-model",
+                    "pipeline_mode": "standard",
+                    "agent_count": 3,
+                    "critic_enabled": False,
+                }
+            ),
+            stderr="",
+        )
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+
+    result = generate_prompt(
+        family,
+        invocation,
+        item_id="B-001",
+        session_id="B-001-session",
+        run_id="run-test",
+        retry_count=0,
+        session_paths=session_paths,
+        project_root=paths.project_root,
+    )
+
+    assert result.model == "per-item-model"
+    assert result.output_path == session_paths.prompt_path
+    assert result.artifact_path == paths.project_root / ".prizmkit" / "bugfix" / "B-001"
+
+
+def test_prompt_generation_passes_explicit_execution_root_to_generator(monkeypatch, tmp_path):
+    from prizmkit_runtime.runner_models import SessionPaths, family_for, parse_invocation
+    from prizmkit_runtime.runner_prompts import generate_prompt
+
+    paths = _make_paths(tmp_path)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+    session_paths = SessionPaths.for_item(paths.feature_state_dir, "F-001", "F-001-session")
+    execution_root = tmp_path / "worktrees" / "dev-F-001"
+
+    def fake_run(command, **kwargs):
+        assert kwargs["cwd"] == str(paths.project_root)
+        assert "--project-root" in command
+        assert command[command.index("--project-root") + 1] == str(execution_root)
+        return subprocess.CompletedProcess(
+            command,
+            0,
+            stdout=json.dumps(
+                {
+                    "success": True,
+                    "output_path": str(session_paths.prompt_path),
+                    "checkpoint_path": str(execution_root / ".prizmkit" / "specs" / "001-low" / "workflow-checkpoint.json"),
+                    "model": "",
+                    "pipeline_mode": "lite",
+                    "agent_count": 1,
+                    "critic_enabled": False,
+                }
+            ),
+            stderr="",
+        )
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+
+    result = generate_prompt(
+        family,
+        invocation,
+        item_id="F-001",
+        session_id="F-001-session",
+        run_id="run-test",
+        retry_count=0,
+        session_paths=session_paths,
+        project_root=paths.project_root,
+        execution_root=execution_root,
+    )
+
+    assert result.artifact_path == execution_root / ".prizmkit" / "specs" / "001-low"
+
+
+def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",), update_status="completed"):
+    from prizmkit_runtime.runner_models import PromptGenerationResult, SessionClassification
+
+    prompt_calls = []
+    launch_cwds = []
+    updates = []
+    cleanup_calls = []
+    merge_calls = []
+    wip_calls = []
+    status_queue = list(statuses)
+
+    monkeypatch.setattr(
+        runners,
+        "load_runtime_config",
+        lambda paths: SimpleNamespace(
+            ai_client=SimpleNamespace(command="fake-ai", platform="codebuddy"),
+            model="fallback-model",
+            effort=None,
+        ),
+    )
+    monkeypatch.setattr(runners, "detect_stream_json_support", lambda command, platform: SimpleNamespace(enabled=False))
+    monkeypatch.setattr(runners, "start_item", lambda *args, **kwargs: SimpleNamespace(ok=True, text="", data={"new_status": "in_progress"}))
+    monkeypatch.setattr(runners, "commit_pre_branch_bookkeeping", lambda *args, **kwargs: None)
+    monkeypatch.setattr(runners, "commit_final_bookkeeping", lambda *args, **kwargs: None)
+    monkeypatch.setattr(runners, "current_branch", lambda _root: "main")
+    monkeypatch.setattr(runners, "_session_id", lambda item_id: f"{item_id}-session-{len(prompt_calls) + 1}")
+    monkeypatch.setattr(
+        runners,
+        "run_git_command",
+        lambda project_root, args: SimpleNamespace(return_code=0, stdout="base-head\n", stderr="", args=tuple(args)),
+    )
+
+    def fake_generate_prompt(family, invocation, **kwargs):
+        prompt_calls.append(kwargs)
+        session_paths = kwargs["session_paths"]
+        execution_root = kwargs.get("execution_root") or kwargs["project_root"]
+        return PromptGenerationResult(
+            output_path=session_paths.prompt_path,
+            model="per-item-model",
+            pipeline_mode="lite",
+            agent_count=1,
+            critic_enabled=False,
+            checkpoint_path=execution_root / ".prizmkit" / "specs" / "001-low" / "workflow-checkpoint.json",
+            artifact_path=execution_root / ".prizmkit" / "specs" / "001-low",
+            raw={},
+        )
+
+    class FakeLauncher:
+        def __init__(self, config):
+            self.config = config
+
+        def run(self):
+            launch_cwds.append(self.config.cwd)
+            return SimpleNamespace(progress_summary=SimpleNamespace(), fatal_error_code="")
+
+    def fake_classify(*args, **kwargs):
+        status = status_queue.pop(0)
+        return SessionClassification(
+            status,
+            reason=status,
+            fatal_error_code="context_overflow" if status == "context_overflow" else "",
+            progress_fingerprint={"head_commit": status},
+            no_progress_count=0,
+        )
+
+    def fake_update(family, invocation, item_id, session_status, session_id, project_root, **metadata):
+        updates.append((session_status, session_id, metadata))
+        return SimpleNamespace(ok=True, text="", data={"new_status": update_status})
+
+    def fake_cleanup(runtime, *, delete_branch=True):
+        cleanup_calls.append((runtime, delete_branch))
+        return SimpleNamespace(ok=True, reason="")
+
+    def fake_merge(runtime, *, auto_push=False):
+        merge_calls.append((runtime, auto_push))
+        return SimpleNamespace(ok=True, reason="", runtime=runtime, results=())
+
+    def fake_save_wip(runtime):
+        wip_calls.append(runtime)
+        return SimpleNamespace(ok=True, plan=None, results=())
+
+    monkeypatch.setattr(runners, "generate_prompt", fake_generate_prompt)
+    monkeypatch.setattr(runners, "AISessionLauncher", FakeLauncher)
+    monkeypatch.setattr(runners, "classify_session", fake_classify)
+    monkeypatch.setattr(runners, "update_item", fake_update)
+    monkeypatch.setattr(runners, "guarded_worktree_remove", fake_cleanup, raising=False)
+    monkeypatch.setattr(runners, "merge_linked_worktree", fake_merge, raising=False)
+    monkeypatch.setattr(runners, "worktree_save_wip", fake_save_wip, raising=False)
+    return SimpleNamespace(
+        prompt_calls=prompt_calls,
+        launch_cwds=launch_cwds,
+        updates=updates,
+        cleanup_calls=cleanup_calls,
+        merge_calls=merge_calls,
+        wip_calls=wip_calls,
+    )
+
+
+@pytest.mark.parametrize(("kind", "item_id", "branch"), [("feature", "F-001", "dev/F-001-test"), ("bugfix", "B-001", "bugfix/B-001-test")])
+def test_feature_and_bugfix_default_worktree_launches_from_worktree_and_renders_worktree_root(monkeypatch, tmp_path, kind, item_id, branch):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    monkeypatch.setenv("DEV_BRANCH", branch)
+    paths = _make_paths(tmp_path / kind)
+    family = family_for(kind, paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan if kind == "feature" else paths.bugfix_plan})
+    observed = _install_runner_session_fakes(monkeypatch, runners)
+    setup_calls = []
+
+    def fake_setup(runtime):
+        setup_calls.append(runtime)
+        runtime.worktree_path.mkdir(parents=True, exist_ok=True)
+        return SimpleNamespace(ok=True, runtime=runtime, reason="")
+
+    monkeypatch.setattr(runners, "ensure_linked_worktree", fake_setup, raising=False)
+
+    status = runners._process_item(family, invocation, item_id, paths, initial_metadata={})
+
+    expected_worktree = paths.state_dir / "worktrees" / branch.replace("/", "-")
+    assert status == "completed"
+    assert setup_calls[0].worktree_path == expected_worktree.resolve()
+    assert observed.launch_cwds == [expected_worktree.resolve()]
+    assert observed.prompt_calls[0]["project_root"] == paths.project_root
+    assert observed.prompt_calls[0]["execution_root"] == expected_worktree.resolve()
+
+
+def test_successful_worktree_session_merges_cleans_branch_and_honors_auto_push(monkeypatch, tmp_path):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    monkeypatch.setenv("DEV_BRANCH", "dev/F-001-test")
+    monkeypatch.setenv("AUTO_PUSH", "1")
+    paths = _make_paths(tmp_path)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+    observed = _install_runner_session_fakes(monkeypatch, runners)
+    monkeypatch.setattr(runners, "ensure_linked_worktree", lambda runtime: SimpleNamespace(ok=True, runtime=runtime, reason=""), raising=False)
+
+    status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
+
+    assert status == "completed"
+    assert observed.merge_calls and observed.merge_calls[0][1] is True
+    assert observed.cleanup_calls and observed.cleanup_calls[0][1] is True
+
+
+def test_worktree_merge_conflict_writes_session_status_and_updates_merge_conflict(monkeypatch, tmp_path):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    monkeypatch.setenv("DEV_BRANCH", "dev/F-001-test")
+    paths = _make_paths(tmp_path)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+    observed = _install_runner_session_fakes(monkeypatch, runners)
+    monkeypatch.setattr(runners, "ensure_linked_worktree", lambda runtime: SimpleNamespace(ok=True, runtime=runtime, reason=""), raising=False)
+    monkeypatch.setattr(runners, "merge_linked_worktree", lambda runtime, *, auto_push=False: SimpleNamespace(ok=False, reason="merge_conflict", runtime=runtime, results=()), raising=False)
+
+    status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
+
+    assert status == "completed"
+    assert observed.updates[-1][0] == "merge_conflict"
+    assert observed.cleanup_calls[-1][1] is False
+    session_status = json.loads((paths.feature_state_dir / "F-001" / "sessions" / "F-001-session-1" / "session-status.json").read_text(encoding="utf-8"))
+    assert session_status["status"] == "merge_conflict"
+    assert session_status["task_id"] == "F-001"
+    assert session_status["task_type"] == "feature"
+    assert session_status["base_branch"] == "main"
+    assert session_status["active_dev_branch"] == "dev/F-001-test"
+    assert session_status["worktree_path"].endswith("dev-F-001-test")
+
+
+def test_terminal_worktree_failure_saves_wip_and_removes_worktree_without_deleting_branch(monkeypatch, tmp_path):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    monkeypatch.setenv("DEV_BRANCH", "dev/F-001-test")
+    paths = _make_paths(tmp_path)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+    observed = _install_runner_session_fakes(monkeypatch, runners, statuses=("crashed",), update_status="failed")
+    monkeypatch.setattr(runners, "ensure_linked_worktree", lambda runtime: SimpleNamespace(ok=True, runtime=runtime, reason=""), raising=False)
+
+    status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
+
+    assert status == "failed"
+    assert observed.wip_calls
+    assert observed.cleanup_calls[-1][1] is False
+    assert observed.updates[-1][0] == "crashed"
+
+
+def test_default_worktree_materializes_ignored_support_assets_before_prompt_and_launch(monkeypatch, tmp_path):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.paths import resolve_runtime_paths
+    from prizmkit_runtime.runner_models import PromptGenerationResult, SessionClassification, family_for, parse_invocation
+
+    project = tmp_path / "repo"
+    project.mkdir()
+    subprocess.run(["git", "init", "-b", "main"], cwd=project, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=project, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=project, check=True)
+    (project / ".gitignore").write_text(".claude/\n.prizmkit/\n", encoding="utf-8")
+    (project / "tracked.txt").write_text("tracked\n", encoding="utf-8")
+    subprocess.run(["git", "add", ".gitignore", "tracked.txt"], cwd=project, check=True)
+    subprocess.run(["git", "commit", "-m", "base"], cwd=project, check=True, stdout=subprocess.DEVNULL)
+
+    (project / ".claude" / "agents").mkdir(parents=True)
+    (project / ".claude" / "agents" / "prizm-dev-team-dev.md").write_text("dev agent", encoding="utf-8")
+    (project / ".claude" / "team-info.json").write_text("{}", encoding="utf-8")
+    (project / ".prizmkit" / "prizm-docs").mkdir(parents=True)
+    (project / ".prizmkit" / "prizm-docs" / "root.prizm").write_text("PRIZM_VERSION: 1\n", encoding="utf-8")
+    (project / ".prizmkit" / "dev-pipeline" / "scripts").mkdir(parents=True)
+    (project / ".prizmkit" / "dev-pipeline" / "scripts" / "init-dev-team.py").write_text("# init", encoding="utf-8")
+    (project / ".prizmkit" / "config.json").write_text("{}", encoding="utf-8")
+    (project / ".prizmkit" / "manifest.json").write_text("{}", encoding="utf-8")
+
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=project)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+    launch_cwds = []
+
+    monkeypatch.setenv("DEV_BRANCH", "dev/F-001-support-assets")
+    monkeypatch.setattr(
+        runners,
+        "load_runtime_config",
+        lambda paths: SimpleNamespace(
+            ai_client=SimpleNamespace(command="fake-ai", platform="codebuddy"),
+            model="fallback-model",
+            effort=None,
+        ),
+    )
+    monkeypatch.setattr(runners, "detect_stream_json_support", lambda command, platform: SimpleNamespace(enabled=False))
+    monkeypatch.setattr(runners, "start_item", lambda *args, **kwargs: SimpleNamespace(ok=True, text="", data={"new_status": "in_progress"}))
+    monkeypatch.setattr(runners, "commit_pre_branch_bookkeeping", lambda *args, **kwargs: None)
+    monkeypatch.setattr(runners, "commit_final_bookkeeping", lambda *args, **kwargs: None)
+    monkeypatch.setattr(runners, "_session_id", lambda item_id: f"{item_id}-session")
+    monkeypatch.setattr(runners, "update_item", lambda *args, **kwargs: SimpleNamespace(ok=True, text="", data={"new_status": "completed"}))
+
+    def fake_generate_prompt(family, invocation, **kwargs):
+        execution_root = kwargs["execution_root"]
+        assert execution_root != project
+        assert (execution_root / ".claude" / "agents" / "prizm-dev-team-dev.md").is_file()
+        assert (execution_root / ".prizmkit" / "prizm-docs" / "root.prizm").is_file()
+        assert (execution_root / ".prizmkit" / "config.json").is_file()
+        assert (execution_root / ".prizmkit" / "manifest.json").is_file()
+        assert (execution_root / ".prizmkit" / "dev-pipeline" / "scripts" / "init-dev-team.py").is_file()
+        assert not (execution_root / ".prizmkit" / "dev-pipeline" / "run-feature.sh").exists()
+        session_paths = kwargs["session_paths"]
+        return PromptGenerationResult(
+            output_path=session_paths.prompt_path,
+            model="",
+            pipeline_mode="lite",
+            agent_count=1,
+            critic_enabled=False,
+            checkpoint_path=execution_root / ".prizmkit" / "specs" / "001-support" / "workflow-checkpoint.json",
+            artifact_path=execution_root / ".prizmkit" / "specs" / "001-support",
+            raw={},
+        )
+
+    class FakeLauncher:
+        def __init__(self, config):
+            self.config = config
+
+        def run(self):
+            launch_cwds.append(self.config.cwd)
+            return SimpleNamespace(progress_summary=SimpleNamespace(), fatal_error_code="")
+
+    monkeypatch.setattr(runners, "generate_prompt", fake_generate_prompt)
+    monkeypatch.setattr(runners, "AISessionLauncher", FakeLauncher)
+    monkeypatch.setattr(
+        runners,
+        "classify_session",
+        lambda *args, **kwargs: SessionClassification(
+            "success", reason="success", fatal_error_code="",
+            progress_fingerprint={"head_commit": "success"}, no_progress_count=0,
+        ),
+    )
+
+    status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
+
+    assert status == "completed"
+    assert launch_cwds and launch_cwds[0] == paths.state_dir / "worktrees" / "dev-F-001-support-assets"
+    assert not launch_cwds[0].exists()
+
+
+def test_use_worktree_false_preserves_main_worktree_branch_launch(monkeypatch, tmp_path):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    monkeypatch.setenv("USE_WORKTREE", "0")
+    monkeypatch.setenv("DEV_BRANCH", "dev/F-001-test")
+    paths = _make_paths(tmp_path)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+    observed = _install_runner_session_fakes(monkeypatch, runners)
+    plan_names = []
+
+    def fake_run_git_plan(project_root, plan):
+        plan_names.append(plan.name)
+        return SimpleNamespace(ok=True, plan=plan, results=())
+
+    monkeypatch.setattr(runners, "run_git_plan", fake_run_git_plan)
+    monkeypatch.setattr(runners, "ensure_linked_worktree", lambda runtime: (_ for _ in ()).throw(AssertionError("worktree setup should not run")), raising=False)
+
+    status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
+
+    assert status == "completed"
+    assert observed.launch_cwds == [paths.project_root]
+    assert observed.prompt_calls[0].get("execution_root") == paths.project_root
+    assert "branch_create" in plan_names
+    assert "branch_merge" in plan_names
+
+
+def test_context_overflow_reuses_worktree_and_skips_cleanup_until_terminal_outcome(monkeypatch, tmp_path):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    monkeypatch.setenv("DEV_BRANCH", "dev/F-001-test")
+    paths = _make_paths(tmp_path)
+    family = family_for("feature", paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+    observed = _install_runner_session_fakes(monkeypatch, runners, statuses=("context_overflow", "success"))
+    setup_calls = []
+    monkeypatch.setattr(runners, "ensure_linked_worktree", lambda runtime: (setup_calls.append(runtime) or SimpleNamespace(ok=True, runtime=runtime, reason="")), raising=False)
+
+    status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
+
+    assert status == "completed"
+    assert len(setup_calls) == 1
+    assert observed.launch_cwds[0] == observed.launch_cwds[1]
+    assert observed.prompt_calls[0]["execution_root"] == observed.prompt_calls[1]["execution_root"]
+    assert observed.prompt_calls[0].get("continuation") is None
+    assert observed.prompt_calls[1]["continuation"]["previous_session_id"] == "F-001-session-1"
+    assert observed.updates[0][0] == "context_overflow"
+    assert len(observed.cleanup_calls) == 1
+    assert observed.cleanup_calls[0][1] is True
+
+
+def test_classification_preserves_success_before_context_overflow(tmp_path):
+    from prizmkit_runtime.runner_classification import classify_session
+    from prizmkit_runtime.sessions import AISessionCommand, AISessionResult
+    from prizmkit_runtime.status import ProgressSummary
+
+    subprocess.run(["git", "init", "-b", "main"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=tmp_path, check=True)
+    (tmp_path / "base.txt").write_text("base", encoding="utf-8")
+    subprocess.run(["git", "add", "base.txt"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "base"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    base_head = subprocess.run(["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True).stdout.strip()
+    (tmp_path / "done.txt").write_text("done", encoding="utf-8")
+    subprocess.run(["git", "add", "done.txt"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "done"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    log = tmp_path / "session.log"
+    log.write_text("API Error: input exceeds the context window", encoding="utf-8")
+
+    raw = AISessionResult(
+        command=AISessionCommand(("fake",), None, "codebuddy", "stdin"),
+        exit_code=1,
+        timed_out=False,
+        termination_reason=None,
+        stale_marker=None,
+        fatal_error_code="context_overflow",
+        progress_summary=ProgressSummary(fatal_error_code="context_overflow"),
+        session_log=log,
+        backup_log=tmp_path / "backup.log",
+        log_recovery=None,
+        started_epoch=0,
+        ended_epoch=1,
+    )
+
+    classification = classify_session(raw, project_root=tmp_path, base_head=base_head)
+    assert classification.session_status == "success"
+    assert classification.reason == "commit_since_base"
+
+
+def test_classification_stalls_after_repeated_no_progress_context_overflow(tmp_path):
+    from prizmkit_runtime.runner_classification import classify_session, progress_fingerprint
+    from prizmkit_runtime.sessions import AISessionCommand, AISessionResult
+    from prizmkit_runtime.status import ProgressSummary
+
+    log = tmp_path / "session.log"
+    log.write_text("PRIZMKIT_FATAL_ERROR=context_overflow", encoding="utf-8")
+    raw = AISessionResult(
+        command=AISessionCommand(("fake",), None, "codebuddy", "stdin"),
+        exit_code=1,
+        timed_out=False,
+        termination_reason=None,
+        stale_marker=None,
+        fatal_error_code="context_overflow",
+        progress_summary=ProgressSummary(fatal_error_code="context_overflow"),
+        session_log=log,
+        backup_log=tmp_path / "backup.log",
+        log_recovery=None,
+        started_epoch=0,
+        ended_epoch=1,
+    )
+    previous = progress_fingerprint(tmp_path)
+
+    classification = classify_session(
+        raw,
+        project_root=tmp_path,
+        base_head="",
+        previous_fingerprint=previous,
+        previous_no_progress_count=1,
+    )
+
+    assert classification.session_status == "stalled_context_continuation"
+    assert classification.no_progress_count == 2
+
+
+def test_recovery_detector_resolver_prefers_installed_platform_asset(tmp_path):
+    from prizmkit_runtime.paths import resolve_runtime_paths
+    from prizmkit_runtime.runner_recovery import RecoveryDetectorResolver
+
+    project = tmp_path / "project"
+    agents = project / ".agents" / "skills" / "recovery-workflow" / "scripts"
+    claude = project / ".claude" / "command-assets" / "recovery-workflow" / "scripts"
+    agents.mkdir(parents=True)
+    claude.mkdir(parents=True)
+    agent_detector = agents / "detect-recovery-state.py"
+    claude_detector = claude / "detect-recovery-state.py"
+    agent_detector.write_text("# agent", encoding="utf-8")
+    claude_detector.write_text("# claude", encoding="utf-8")
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=project)
+
+    assert RecoveryDetectorResolver(paths).resolve() == agent_detector
+
+
+def test_cli_family_status_uses_python_dispatch_not_transition_description(tmp_path):
+    paths = _make_paths(tmp_path)
+    _write_feature_list(paths)
+    result = subprocess.run(
+        [PYTHON_310_PLUS, str(CLI_PATH), "--project-root", str(paths.project_root), "feature", "status"],
+        cwd=REPO_ROOT,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+
+    assert result.returncode == 0
+    assert "Python feature status" in result.stdout
+    assert "Transition command contract" not in result.stdout
+
+
+def _write_family_case(paths, kind, item_id=""):
+    item_id = item_id or {"feature": "F-001", "bugfix": "B-001", "refactor": "R-001"}[kind]
+    if kind == "feature":
+        paths.feature_plan.write_text(json.dumps({"features": [{"id": item_id, "title": "Reset Thing", "status": "failed", "dependencies": []}]}), encoding="utf-8")
+        state_dir = paths.feature_state_dir
+        plan = paths.feature_plan
+    elif kind == "bugfix":
+        paths.bugfix_plan.write_text(json.dumps({"bugs": [{"id": item_id, "title": "Reset Bug", "description": "d", "severity": "medium", "priority": "medium", "status": "failed"}]}), encoding="utf-8")
+        state_dir = paths.bugfix_state_dir
+        plan = paths.bugfix_plan
+    else:
+        paths.refactor_plan.write_text(json.dumps({"refactors": [{"id": item_id, "title": "Reset Refactor", "description": "d", "complexity": "medium", "priority": "medium", "status": "failed", "dependencies": []}]}), encoding="utf-8")
+        state_dir = paths.refactor_state_dir
+        plan = paths.refactor_plan
+    state_dir.mkdir(parents=True, exist_ok=True)
+    (state_dir / "pipeline.json").write_text("{}", encoding="utf-8")
+    item_state = state_dir / item_id
+    item_state.mkdir(parents=True, exist_ok=True)
+    (item_state / "status.json").write_text(
+        json.dumps(
+            {
+                "status": "in_progress",
+                "retry_count": 2,
+                "infra_error_count": 1,
+                "last_infra_error_session_id": "infra-1",
+                "last_session_id": "sess-1",
+                "sessions": ["sess-1"],
+                "continuation_pending": True,
+                "continuation_reason": "context_overflow",
+                "active_dev_branch": f"{kind}/{item_id}-branch",
+                "continuation_summary_path": str(paths.project_root / ".prizmkit" / ("specs" if kind == "feature" else kind) / item_id / "continuation-summary.md"),
+            }
+        ),
+        encoding="utf-8",
+    )
+    return plan, state_dir, item_state / "status.json"
+
+
+def test_python_reset_warns_before_mutation_and_matches_snapshot_cleanup(tmp_path):
+    from prizmkit_runtime.reset import run_reset_command
+
+    snapshot = json.loads((REPO_ROOT / "tests" / "fixtures" / "dev-pipeline-behavior-snapshots" / "unix-runtime.json").read_text(encoding="utf-8"))
+    for kind, item_id in [("feature", "F-001"), ("bugfix", "B-001"), ("refactor", "R-001")]:
+        paths = _make_paths(tmp_path / kind)
+        _plan, _state_dir, status_file = _write_family_case(paths, kind, item_id)
+        result = run_reset_command(kind, (item_id,), paths)
+        output = result.render()
+        reset_marker = f"Resetting {item_id} status"
+
+        assert result.exit_code == snapshot["resetBehavior"]["manualResetWarningOrder"][kind]["exitCode"]
+        assert "Continuation pending" in output
+        assert "Pending continuation branch" in output
+        assert output.index("Continuation pending") < output.index(reset_marker)
+        runtime = json.loads(status_file.read_text(encoding="utf-8"))
+        expected_runtime = snapshot["statusUpdaterBehavior"]["resetCleanMetadataCleanup"][kind]["reset"]["runtime"]
+        for key, value in expected_runtime.items():
+            assert runtime.get(key) == value
+        assert "continuation_pending" not in runtime
+
+
+def test_python_clean_reset_deletes_continuation_artifacts_for_all_families(tmp_path):
+    from prizmkit_runtime.reset import run_reset_command
+
+    snapshot = json.loads((REPO_ROOT / "tests" / "fixtures" / "dev-pipeline-behavior-snapshots" / "unix-runtime.json").read_text(encoding="utf-8"))
+    cases = [("feature", "F-001", "specs", "001-reset-thing"), ("bugfix", "B-001", "bugfix", "B-001"), ("refactor", "R-001", "refactor", "R-001")]
+    for kind, item_id, artifact_root, artifact_name in cases:
+        paths = _make_paths(tmp_path / f"clean-{kind}")
+        _plan, _state_dir, status_file = _write_family_case(paths, kind, item_id)
+        artifact_dir = paths.project_root / ".prizmkit" / artifact_root / artifact_name
+        artifact_dir.mkdir(parents=True, exist_ok=True)
+        continuation = artifact_dir / "continuation-summary.md"
+        continuation.write_text("summary", encoding="utf-8")
+        args = (item_id, "--clean")
+        result = run_reset_command(kind, args, paths)
+
+        assert result.exit_code == snapshot["resetBehavior"]["cleanResetDeletesContinuationArtifacts"][kind]["exitCode"]
+        assert continuation.exists() is False
+        runtime = json.loads(status_file.read_text(encoding="utf-8"))
+        assert runtime.get("retry_count") == 0
+        assert runtime.get("infra_error_count") == 0
+        assert "continuation_pending" not in runtime
+
+
+def test_python_context_overflow_runner_path_does_not_import_reset():
+    runner_text = (PIPELINE_ROOT / "prizmkit_runtime" / "runners.py").read_text(encoding="utf-8")
+
+    assert "from .reset" not in runner_text
+    assert "run_reset_command" not in runner_text
+    assert '"context_overflow"' in runner_text
+    assert "update_item" in runner_text
+
+
+def test_python_daemon_stale_pid_matches_snapshot(tmp_path):
+    from prizmkit_runtime.daemon import run_daemon_command
+
+    snapshot = json.loads((REPO_ROOT / "tests" / "fixtures" / "dev-pipeline-behavior-snapshots" / "unix-runtime.json").read_text(encoding="utf-8"))
+    for kind in ("feature", "bugfix", "refactor"):
+        paths = _make_paths(tmp_path / f"daemon-{kind}")
+        family_state = {"feature": paths.feature_state_dir, "bugfix": paths.bugfix_state_dir, "refactor": paths.refactor_state_dir}[kind]
+        family_state.mkdir(parents=True, exist_ok=True)
+        pid_file = family_state / ".pipeline.pid"
+        pid_file.write_text("999999\n", encoding="utf-8")
+        result = run_daemon_command(kind, "status", (), paths)
+        expected = snapshot["daemonBehavior"]["stalePidStatusByTaskType"][kind]
+
+        assert result.exit_code == expected["exitCode"]
+        assert json.loads(result.render())["running"] is False
+        assert pid_file.exists() is False
+        assert "Cleaned stale PID file" in (result.stderr or "")
+
+
+def test_python_daemon_controlled_start_status_stop_matches_snapshot(tmp_path):
+    from prizmkit_runtime.daemon import run_daemon_command
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    snapshot = json.loads((REPO_ROOT / "tests" / "fixtures" / "dev-pipeline-behavior-snapshots" / "unix-runtime.json").read_text(encoding="utf-8"))["daemonBehavior"]["controlledStartStop"]
+    project = tmp_path / "project"
+    pipeline = tmp_path / "runtime"
+    pipeline.mkdir(parents=True)
+    cli = pipeline / "cli.py"
+    cli.write_text(
+        "#!/usr/bin/env python3\n"
+        "import os, sys, time\n"
+        "print('payload env=' + os.environ.get('FOO', ''))\n"
+        "print('payload args=' + ' '.join(sys.argv[1:]))\n"
+        "sys.stdout.flush()\n"
+        "time.sleep(30)\n",
+        encoding="utf-8",
+    )
+    cli.chmod(0o755)
+    paths = resolve_runtime_paths(pipeline_root=pipeline, project_root=project)
+    paths.plans_dir.mkdir(parents=True)
+    paths.feature_plan.write_text(json.dumps({"features": [{"id": "F-001", "title": "A", "status": "pending"}]}), encoding="utf-8")
+
+    start = run_daemon_command("feature", "start", ("--env", "FOO=bar", "--features", "F-001"), paths)
+    try:
+        start_payload = json.loads(start.render())
+        status = run_daemon_command("feature", "status", (), paths)
+        status_payload = json.loads(status.render())
+    finally:
+        stop = run_daemon_command("feature", "stop", (), paths)
+
+    assert start.exit_code == snapshot["startExitCode"]
+    assert start_payload["success"] is snapshot["startSuccess"]
+    assert isinstance(start_payload["pid"], int)
+    assert (paths.feature_state_dir / ".pipeline.pid").exists() is snapshot["pidFileExistsAfterStop"]
+    assert status.exit_code == snapshot["statusWhileRunningExitCode"]
+    assert status_payload["running"] is snapshot["statusWhileRunningReportsRunning"]
+    assert isinstance(status_payload["pid"], int)
+    assert status_payload["log_file"].endswith("pipeline-daemon.log")
+    assert stop.exit_code == snapshot["stopExitCode"]
+    assert json.loads(stop.render())["message"] in {"stopped", "already exited", "not running"}
+    log_text = (paths.feature_state_dir / "pipeline-daemon.log").read_text(encoding="utf-8")
+    assert "FOO=bar" in log_text or "payload env=bar" in log_text
+    assert "--project-root" in log_text
+
+
+def test_python_reset_stalled_filter_selects_stalled_context_items(tmp_path):
+    from prizmkit_runtime.reset import run_reset_command
+
+    status_by_kind = {
+        "feature": ("features", "F-001"),
+        "bugfix": ("bugs", "B-001"),
+        "refactor": ("refactors", "R-001"),
+    }
+    for kind, (_collection, item_id) in status_by_kind.items():
+        paths = _make_paths(tmp_path / f"stalled-{kind}")
+        plan, _state_dir, status_file = _write_family_case(paths, kind, item_id)
+        data = json.loads(plan.read_text(encoding="utf-8"))
+        data[{"feature": "features", "bugfix": "bugs", "refactor": "refactors"}[kind]][0]["status"] = "stalled_context_continuation"
+        plan.write_text(json.dumps(data), encoding="utf-8")
+
+        result = run_reset_command(kind, ("--stalled",), paths)
+
+        assert result.exit_code == 0
+        assert f"Reset: {item_id}" in result.render()
+        runtime = json.loads(status_file.read_text(encoding="utf-8"))
+        assert runtime.get("retry_count") == 0
+        assert "continuation_pending" not in runtime
+        updated = json.loads(plan.read_text(encoding="utf-8"))
+        assert updated[{"feature": "features", "bugfix": "bugs", "refactor": "refactors"}[kind]][0]["status"] == "pending"
+
+
+def test_python_daemon_progress_uses_list_status_without_runtime_files(tmp_path):
+    from prizmkit_runtime.daemon import _progress_summary
+    from prizmkit_runtime.runner_models import family_for
+
+    for kind in ("feature", "bugfix", "refactor"):
+        paths = _make_paths(tmp_path / f"progress-{kind}")
+        if kind == "feature":
+            paths.feature_plan.write_text(
+                json.dumps({"features": [
+                    {"id": "F-001", "title": "Done", "status": "completed"},
+                    {"id": "F-002", "title": "Failed", "status": "failed"},
+                    {"id": "F-003", "title": "Skipped", "status": "auto_skipped"},
+                ]}),
+                encoding="utf-8",
+            )
+            plan = paths.feature_plan
+        elif kind == "bugfix":
+            paths.bugfix_plan.write_text(
+                json.dumps({"bugs": [
+                    {"id": "B-001", "title": "Done", "status": "completed"},
+                    {"id": "B-002", "title": "Failed", "status": "failed"},
+                    {"id": "B-003", "title": "Needs Info", "status": "needs_info"},
+                ]}),
+                encoding="utf-8",
+            )
+            plan = paths.bugfix_plan
+        else:
+            paths.refactor_plan.write_text(
+                json.dumps({"refactors": [
+                    {"id": "R-001", "title": "Done", "status": "completed"},
+                    {"id": "R-002", "title": "Failed", "status": "failed"},
+                    {"id": "R-003", "title": "Skipped", "status": "auto_skipped"},
+                ]}),
+                encoding="utf-8",
+            )
+            plan = paths.refactor_plan
+
+        summary = _progress_summary(family_for(kind, paths), plan)
+
+        assert summary["total"] == 3
+        assert summary["completed"] == 1
+        assert summary["failed"] == 1
+        assert summary["percent"] == 33.3
+        if kind == "bugfix":
+            assert summary["needs_info"] == 1
+        else:
+            assert summary["auto_skipped"] == 1
+