prizmkit 1.1.152 → 1.1.154

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

@@ -54,23 +54,16 @@ def _load_progress_parser_module():
     return module
 
 
-def test_cli_help_exposes_python_runtime_command_groups():
+def test_cli_help_exposes_only_operation_first_public_namespaces():
     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 "operation-first" in result.stdout
+    for group in ["run", "status", "reset", "daemon", "diagnostics", "helper"]:
         assert group in result.stdout
+    for removed in ["feature", "bugfix", "refactor", "recovery"]:
+        assert removed not in result.stdout.lower()
     assert "Traceback" not in result.stderr
 
 
@@ -79,7 +72,7 @@ def test_cli_help_preserves_runtime_identity_at_narrow_terminal_width():
 
     assert result.returncode == 0
     assert "canonical Python runtime CLI" in result.stdout
-    assert "without shell wrappers" in result.stdout
+    assert "operation-first" in result.stdout
 
 
 def test_module_entrypoint_help_exposes_same_cli():
@@ -99,6 +92,45 @@ def test_module_entrypoint_help_exposes_same_cli():
     assert "diagnostics" in result.stdout
 
 
+@pytest.mark.parametrize(
+    "args",
+    [
+        ("--help",),
+        ("run", "--help"),
+        ("run", "feature", "--help"),
+        ("run", "bugfix", "--help"),
+        ("run", "refactor", "--help"),
+        ("status", "--help"),
+        ("status", "feature", "--help"),
+        ("status", "all", "--help"),
+        ("reset", "--help"),
+        ("reset", "feature", "--help"),
+        ("daemon", "--help"),
+        ("daemon", "feature", "--help"),
+        ("daemon", "feature", "start", "--help"),
+        ("daemon", "bugfix", "stop", "--help"),
+        ("daemon", "refactor", "status", "--help"),
+        ("daemon", "feature", "logs", "--help"),
+        ("daemon", "feature", "restart", "--help"),
+        ("diagnostics", "--help"),
+        ("diagnostics", "ai-cli", "--help"),
+        ("helper", "--help"),
+    ],
+)
+def test_help_at_every_namespace_depth_is_parser_owned_and_never_dispatches(monkeypatch, args):
+    from prizmkit_runtime import cli as runtime_cli
+
+    dispatched = []
+    monkeypatch.setattr(runtime_cli, "ensure_supported_python", lambda: None)
+    monkeypatch.setattr(runtime_cli, "_dispatch", lambda parsed: dispatched.append(parsed))
+
+    with pytest.raises(SystemExit) as exc_info:
+        runtime_cli.main(list(args))
+
+    assert exc_info.value.code == 0
+    assert dispatched == []
+
+
 def test_invalid_arguments_report_usage_without_traceback():
     result = run_cli("unknown-command")
 
@@ -108,6 +140,80 @@ def test_invalid_arguments_report_usage_without_traceback():
     assert "Traceback" not in result.stderr
 
 
+@pytest.mark.parametrize(
+    "args",
+    [
+        ("recovery",),
+        ("recovery", "detect"),
+        ("recovery", "run"),
+        ("recovery", "describe"),
+        ("recovery", "run", "--dry-run"),
+    ],
+)
+def test_former_recovery_invocations_are_unknown_commands(args):
+    result = run_cli(*args)
+
+    assert result.returncode == 2
+    assert "invalid choice: 'recovery'" in result.stderr
+    assert "Traceback" not in result.stderr
+
+
+def test_former_recovery_invocation_never_reaches_dispatch(monkeypatch):
+    from prizmkit_runtime import cli as runtime_cli
+
+    dispatched = []
+    monkeypatch.setattr(runtime_cli, "ensure_supported_python", lambda: None)
+    monkeypatch.setattr(runtime_cli, "_dispatch", lambda args: dispatched.append(args))
+
+    with pytest.raises(SystemExit) as exc_info:
+        runtime_cli.main(["recovery", "run", "--dry-run"])
+
+    assert exc_info.value.code == 2
+    assert dispatched == []
+
+
+@pytest.mark.parametrize(
+    "args",
+    [
+        ("feature", "run"),
+        ("feature", "status"),
+        ("feature", "reset"),
+        ("feature", "unskip"),
+        ("feature", "test-cli"),
+        ("feature", "describe"),
+        ("bugfix", "run"),
+        ("bugfix", "status"),
+        ("bugfix", "reset"),
+        ("bugfix", "unskip"),
+        ("bugfix", "describe"),
+        ("refactor", "run"),
+        ("refactor", "status"),
+        ("refactor", "reset"),
+        ("refactor", "unskip"),
+        ("refactor", "describe"),
+        ("reset", "describe"),
+        ("daemon", "feature", "describe"),
+        ("diagnostics", "describe"),
+        ("status", "all", "custom-plan.json"),
+        ("run", "feature", "--unknown-option"),
+        ("run", "feature", "F-001", "plan.json", "extra"),
+        ("daemon", "feature", "status", "extra"),
+    ],
+)
+def test_removed_or_invalid_forms_fail_in_parser_without_runtime_dispatch(monkeypatch, args):
+    from prizmkit_runtime import cli as runtime_cli
+
+    dispatched = []
+    monkeypatch.setattr(runtime_cli, "ensure_supported_python", lambda: None)
+    monkeypatch.setattr(runtime_cli, "_dispatch", lambda parsed: dispatched.append(parsed))
+
+    with pytest.raises(SystemExit) as exc_info:
+        runtime_cli.main(list(args))
+
+    assert exc_info.value.code == 2
+    assert dispatched == []
+
+
 def test_python_version_guard_mentions_required_version():
     from prizmkit_runtime.compat import UnsupportedPythonVersion, ensure_supported_python
 
@@ -136,6 +242,7 @@ def test_runtime_paths_support_framework_source_layout():
     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 not hasattr(paths, "recovery_state_dir")
     assert all(isinstance(value, Path) for value in paths.path_values())
 
 
@@ -154,6 +261,22 @@ def test_runtime_paths_support_installed_layout(tmp_path):
     assert paths.logs_dir == paths.state_dir / "logs"
 
 
+def test_runtime_diagnostics_leave_historical_recovery_state_untouched(tmp_path):
+    project = tmp_path / "project"
+    historical = project / ".prizmkit" / "state" / "recovery" / "historical-session"
+    historical.mkdir(parents=True)
+    marker = historical / "marker.json"
+    marker.write_bytes(b'{"preserve": true}\n')
+    before = {path.relative_to(project).as_posix(): path.read_bytes() for path in historical.rglob("*") if path.is_file()}
+
+    result = run_cli("--project-root", str(project), "diagnostics", "paths")
+
+    after = {path.relative_to(project).as_posix(): path.read_bytes() for path in historical.rglob("*") if path.is_file()}
+    assert result.returncode == 0
+    assert before == after
+    assert marker.is_file()
+
+
 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
@@ -298,59 +421,51 @@ def test_runtime_config_supplied_env_does_not_leak_ambient_path(tmp_path):
 
 
 
-    from prizmkit_runtime.commands import list_runtime_commands
+def test_runtime_command_registry_contains_only_executing_operation_first_entries():
+    from prizmkit_runtime.commands import find_runtime_command, 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"),
+        *(('run', family, 'run') for family in ('feature', 'bugfix', 'refactor')),
+        *(('status', family, 'status') for family in ('feature', 'bugfix', 'refactor', 'all')),
+        *(('reset', family, 'reset') for family in ('feature', 'bugfix', 'refactor')),
+        *(('daemon', family, action)
+          for family in ('feature', 'bugfix', 'refactor')
+          for action in ('start', 'stop', 'status', 'logs', 'restart')),
+        *(('diagnostics', None, action)
+          for action in ('paths', 'entrypoints', 'version', 'ai-cli')),
+        ('helper', None, 'run'),
     }
-    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)
 
+    assert command_keys == expected
+    assert all(command.current_entrypoint for command in list_runtime_commands())
+    assert all(command.action != "describe" for command in list_runtime_commands())
+    assert all(command.group not in {"feature", "bugfix", "refactor", "recovery"} for command in list_runtime_commands())
+    for removed in [
+        ("feature", "run", None),
+        ("feature", "test-cli", None),
+        ("reset", "describe", None),
+        ("daemon", "describe", "feature"),
+        ("recovery", "detect", None),
+    ]:
+        with pytest.raises(KeyError, match="Unknown runtime command"):
+            find_runtime_command(removed[0], removed[1], removed[2])
 
-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_removed_describe_commands_are_rejected():
+    for args in [
+        ("feature", "describe"),
+        ("reset", "describe"),
+        ("daemon", "feature", "describe"),
+        ("diagnostics", "describe"),
+    ]:
+        result = run_cli(*args)
+        assert result.returncode == 2
+        assert "invalid choice" in result.stderr
+        assert "Python runtime command contract" not in result.stdout
 
 
-def test_option_first_runtime_arguments_are_forwarded(monkeypatch):
+def test_operation_first_runtime_arguments_are_validated_then_forwarded_exactly(monkeypatch):
     from prizmkit_runtime import cli as runtime_cli
 
     captured = []
@@ -362,8 +477,16 @@ def test_option_first_runtime_arguments_are_forwarded(monkeypatch):
     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",))
+    run_args = [
+        "run", "feature", "F-001", "custom.json", "--features", "F-001:F-005",
+        "--max-retries", "5", "--max-infra-retries", "4", "--mode", "full",
+        "--resume-phase", "6", "--dry-run",
+    ]
+    assert runtime_cli.main(run_args) == 0
+    assert captured[-1] == ("run", "run", "feature", tuple(run_args[2:]))
+
+    assert runtime_cli.main(["status", "bugfix", "bugs.json"]) == 0
+    assert captured[-1] == ("status", "status", "bugfix", ("bugs.json",))
 
     assert runtime_cli.main(["daemon", "feature", "start", "--mode", "standard"]) == 0
     assert captured[-1] == ("daemon", "start", "feature", ("--mode", "standard"))
@@ -371,67 +494,104 @@ def test_option_first_runtime_arguments_are_forwarded(monkeypatch):
     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(["reset", "feature", "--failed", "--preserve-runtime"]) == 0
+    assert captured[-1] == ("reset", "reset", "feature", ("--failed", "--preserve-runtime"))
+
+    interspersed_reset = ["reset", "feature", "F-001", "--fresh-checkout", "custom.json"]
+    assert runtime_cli.main(interspersed_reset) == 0
+    assert captured[-1] == (
+        "reset", "reset", "feature", ("F-001", "--fresh-checkout", "custom.json")
+    )
 
-    assert runtime_cli.main(["--project-root", "feature", "feature", "describe"]) == 0
-    assert captured[-1] == ("feature", "describe", None, ())
+    interspersed_daemon = ["daemon", "feature", "start", "--mode", "full", "custom.json"]
+    assert runtime_cli.main(interspersed_daemon) == 0
+    assert captured[-1] == (
+        "daemon", "start", "feature", ("--mode", "full", "custom.json")
+    )
 
+    assert runtime_cli.main(["--project-root", "feature", "run", "feature", "--dry-run"]) == 0
+    assert captured[-1] == ("run", "run", "feature", ("--dry-run",))
 
-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 = ""
+@pytest.mark.parametrize(
+    ("family", "task_id", "extra_args"),
+    [
+        ("feature", "F-007", ("--features", "F-007", "--dry-run")),
+        ("bugfix", "B-007", ("--mode", "full", "--max-retries", "4")),
+        ("refactor", "R-007", ("--resume-phase", "6", "--max-infra-retries", "5")),
+    ],
+)
+def test_run_family_dispatch_preserves_each_family_argument_tail(
+    monkeypatch, family, task_id, extra_args
+):
+    from prizmkit_runtime import cli as runtime_cli
 
     captured = []
+    monkeypatch.setattr(runtime_cli, "ensure_supported_python", lambda: None)
+    monkeypatch.setattr(
+        runtime_cli,
+        "handle_runtime_command",
+        lambda group, action, **kwargs: captured.append(
+            (group, action, kwargs["target"], kwargs["legacy_args"])
+        ) or runtime_cli.CommandResult(0, "ok", "ok"),
+    )
+    argv = ["run", family, task_id, *extra_args]
 
-    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()
+    assert runtime_cli.main(argv) == 0
+    assert captured == [("run", "run", family, (task_id, *extra_args))]
 
-    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",))
+@pytest.mark.parametrize("family", ("feature", "bugfix", "refactor"))
+@pytest.mark.parametrize("legacy_action", ("reset", "un" + "skip"))
+def test_family_level_reset_aliases_are_not_public_commands(family, legacy_action):
+    result = run_cli(family, legacy_action)
 
-    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())]
+    assert result.returncode == 2
+    assert "invalid choice" in result.stderr
 
 
-def test_test_cli_reports_ai_resolution_not_contract(monkeypatch):
-    from prizmkit_runtime import runners
-    from prizmkit_runtime.commands import handle_runtime_command
+def test_diagnostics_ai_cli_reports_family_neutral_resolution(monkeypatch):
+    from prizmkit_runtime import config
+    from prizmkit_runtime.commands import handle_diagnostics
     from prizmkit_runtime.paths import resolve_runtime_paths
 
     class FakeAIClient:
         command = "claude"
         platform = "claude"
         source = "test"
-        notes = ()
+        notes = ("configured globally",)
 
     class FakeConfig:
         ai_client = FakeAIClient()
         runtime_mode = "python-runtime-canonical"
         model = "claude-sonnet-4.6"
 
-    monkeypatch.setattr(runners, "load_runtime_config", lambda paths: FakeConfig())
+    monkeypatch.setattr(config, "load_runtime_config", lambda paths: FakeConfig())
     paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT)
 
-    result = handle_runtime_command("feature", "test-cli", paths=paths)
+    result = handle_diagnostics("ai-cli", paths)
     rendered = result.render()
 
     assert result.exit_code == 0
-    assert result.title == "Python feature AI CLI test"
+    assert result.title == "Python runtime AI CLI diagnostics"
     assert "detected_cli: claude" in rendered
-    assert "Python runtime command contract" not in rendered
+    assert "platform: claude" in rendered
+    assert "source: test" in rendered
+    assert "runtime_mode: python-runtime-canonical" in rendered
+    assert "model: claude-sonnet-4.6" in rendered
+    assert "note: configured globally" in rendered
+    assert "feature" not in result.title.lower()
+
+
+def test_diagnostics_help_exposes_only_real_diagnostic_actions():
+    result = run_cli("diagnostics", "--help")
+
+    assert result.returncode == 0
+    for action in ("paths", "entrypoints", "version", "ai-cli"):
+        assert action in result.stdout
+    assert "describe" not in result.stdout
+    assert "commands" not in result.stdout
+    assert "test-cli" not in result.stdout
 
 
 def test_diagnostics_paths_and_entrypoints_are_standard_library_cli_actions():
@@ -444,8 +604,180 @@ def test_diagnostics_paths_and_entrypoints_are_standard_library_cli_actions():
     assert entrypoints_result.returncode == 0
     assert "Python runtime entrypoint inventory" in entrypoints_result.stdout
     assert "runtime:cli:" in entrypoints_result.stdout
+    assert "command:run:feature: python3 dev-pipeline/cli.py run feature" in entrypoints_result.stdout
+    assert "command:status:all: python3 dev-pipeline/cli.py status all" in entrypoints_result.stdout
+    assert "command:diagnostics:ai-cli:" in entrypoints_result.stdout
+    assert " describe" not in entrypoints_result.stdout
+    assert "test-cli" not in entrypoints_result.stdout
     assert "run-feature.sh" not in entrypoints_result.stdout
     assert "generate-bootstrap-prompt.py" in entrypoints_result.stdout
+    assert "generate-recovery-prompt.py" not in entrypoints_result.stdout
+
+
+def _write_family_status_plan(paths, family, task_id):
+    plan_path, key = {
+        "feature": (paths.feature_plan, "features"),
+        "bugfix": (paths.bugfix_plan, "bugs"),
+        "refactor": (paths.refactor_plan, "refactors"),
+    }[family]
+    plan_path.parent.mkdir(parents=True, exist_ok=True)
+    plan_path.write_text(json.dumps({key: [{"id": task_id, "status": "pending"}]}), encoding="utf-8")
+    return plan_path
+
+
+def _file_bytes_under(root):
+    if not root.exists():
+        return {}
+    return {
+        path.relative_to(root).as_posix(): path.read_bytes()
+        for path in root.rglob("*")
+        if path.is_file()
+    }
+
+
+def test_status_all_aggregates_configured_families_in_fixed_order_and_missing_is_nonfatal(
+    tmp_path, monkeypatch
+):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.commands import CommandResult, handle_runtime_command
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=tmp_path)
+    _write_family_status_plan(paths, "feature", "F-001")
+    _write_family_status_plan(paths, "refactor", "R-001")
+    before = _file_bytes_under(tmp_path)
+    calls = []
+
+    def fake_status(family, action, legacy_args, runtime_paths):
+        calls.append((family, action, legacy_args, runtime_paths))
+        return CommandResult(0, f"Python {family} status", f"normal {family} status")
+
+    monkeypatch.setattr(runners, "run_pipeline_command", fake_status)
+    result = handle_runtime_command("status", "status", target="all", paths=paths)
+    rendered = result.render()
+
+    assert result.exit_code == 0
+    assert rendered.index("FEATURE\n=======") < rendered.index("BUGFIX\n======")
+    assert rendered.index("BUGFIX\n======") < rendered.index("REFACTOR\n========")
+    assert "normal feature status" in rendered
+    assert "normal refactor status" in rendered
+    assert "BUGFIX\n======\nnot configured: plan list not found" in rendered
+    assert [(family, action, args) for family, action, args, _paths in calls] == [
+        ("feature", "status", ()),
+        ("refactor", "status", ()),
+    ]
+    assert _file_bytes_under(tmp_path) == before
+    assert not paths.feature_state_dir.exists()
+    assert not paths.bugfix_state_dir.exists()
+    assert not paths.refactor_state_dir.exists()
+
+
+def test_status_all_uses_real_family_status_handlers_without_filesystem_mutation(tmp_path):
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=tmp_path)
+    feature_plan = _write_family_status_plan(paths, "feature", "F-001")
+    refactor_plan = _write_family_status_plan(paths, "refactor", "R-001")
+    before = {
+        path.relative_to(tmp_path).as_posix(): (path.read_bytes(), path.stat().st_mtime_ns)
+        for path in (feature_plan, refactor_plan)
+    }
+
+    result = run_cli("--project-root", str(tmp_path), "status", "all")
+
+    after = {
+        path.relative_to(tmp_path).as_posix(): (path.read_bytes(), path.stat().st_mtime_ns)
+        for path in (feature_plan, refactor_plan)
+    }
+    assert result.returncode == 0, result.stderr
+    assert "FEATURE\n=======" in result.stdout
+    assert "Python feature status" in result.stdout
+    assert "BUGFIX\n======\nnot configured: plan list not found" in result.stdout
+    assert "REFACTOR\n========" in result.stdout
+    assert "Python refactor status" in result.stdout
+    assert after == before
+    assert not paths.feature_state_dir.exists()
+    assert not paths.bugfix_state_dir.exists()
+    assert not paths.refactor_state_dir.exists()
+
+
+def test_status_all_reports_plan_and_handler_errors_but_renders_unaffected_sections(
+    tmp_path, monkeypatch
+):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.commands import CommandResult, handle_runtime_command
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=tmp_path)
+    _write_family_status_plan(paths, "feature", "F-001")
+    paths.bugfix_plan.parent.mkdir(parents=True, exist_ok=True)
+    paths.bugfix_plan.write_text("{malformed", encoding="utf-8")
+    _write_family_status_plan(paths, "refactor", "R-001")
+
+    def fake_status(family, action, legacy_args, runtime_paths):
+        assert action == "status"
+        if family == "refactor":
+            raise RuntimeError("family handler exploded")
+        return CommandResult(0, f"Python {family} status", f"normal {family} status")
+
+    monkeypatch.setattr(runners, "run_pipeline_command", fake_status)
+    result = handle_runtime_command("status", "status", target="all", paths=paths)
+    rendered = result.render()
+
+    assert result.exit_code != 0
+    assert "FEATURE\n=======\nPython feature status\nnormal feature status" in rendered
+    assert "BUGFIX\n======\nerror: malformed plan list:" in rendered
+    assert "REFACTOR\n========\nerror: family handler exploded" in rendered
+
+
+def test_status_all_reports_malformed_runtime_unparseable_and_nonzero_results(
+    tmp_path, monkeypatch
+):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.commands import CommandResult, handle_runtime_command
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=tmp_path)
+    _write_family_status_plan(paths, "feature", "F-001")
+    _write_family_status_plan(paths, "bugfix", "B-001")
+    _write_family_status_plan(paths, "refactor", "R-001")
+    malformed_state = paths.feature_state_dir / "F-001" / "status.json"
+    malformed_state.parent.mkdir(parents=True, exist_ok=True)
+    malformed_state.write_text("not-json", encoding="utf-8")
+
+    def fake_status(family, action, legacy_args, runtime_paths):
+        if family == "bugfix":
+            return object()
+        return CommandResult(7 if family == "refactor" else 0, f"Python {family} status", "status output")
+
+    monkeypatch.setattr(runners, "run_pipeline_command", fake_status)
+    result = handle_runtime_command("status", "status", target="all", paths=paths)
+    rendered = result.render()
+
+    assert result.exit_code != 0
+    assert "FEATURE\n=======\nerror: malformed runtime state F-001/status.json" in rendered
+    assert "BUGFIX\n======\nerror: unparseable configured family result" in rendered
+    assert "REFACTOR\n========\nerror: Python refactor status\nstatus output" in rendered
+
+
+def test_status_all_direct_api_rejects_family_specific_arguments_without_calling_handlers(
+    tmp_path, monkeypatch
+):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.commands import handle_runtime_command
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=tmp_path)
+    called = []
+    monkeypatch.setattr(runners, "run_pipeline_command", lambda *args: called.append(args))
+
+    result = handle_runtime_command(
+        "status", "status", target="all", paths=paths, legacy_args=("custom.json",)
+    )
+
+    assert result.exit_code == 2
+    assert "does not accept a plan path" in result.render()
+    assert called == []
 
 
 def test_interoperability_preserves_existing_utility_mapping():
@@ -481,9 +813,55 @@ def test_interoperability_preserves_existing_utility_mapping():
     assert actual_scripts == mapped_scripts | explicitly_library_only
     assert explicitly_library_only == {"continuation.py", "prompt_framework.py", "utils.py"}
     assert "parse-stream-progress.py" in mapped_scripts
+    assert "generate-recovery-prompt" not in UTILITY_ENTRYPOINTS
     assert "prizmkit-test-gate.py" not in mapped_scripts
 
 
+def test_obsolete_runtime_recovery_ai_session_sources_are_absent():
+    assert not (PIPELINE_ROOT / "prizmkit_runtime" / "runner_recovery.py").exists()
+    assert not (PIPELINE_ROOT / "scripts" / "generate-recovery-prompt.py").exists()
+
+    forbidden_by_source = {
+        "prizmkit_runtime/cli.py": ('"recovery"',),
+        "prizmkit_runtime/commands.py": ('"recovery": ("run"', 'group == "recovery"'),
+        "prizmkit_runtime/runners.py": ("runner_recovery", "run_recovery_command"),
+        "prizmkit_runtime/paths.py": ("recovery_state_dir",),
+        "prizmkit_runtime/interoperability.py": ("generate-recovery-prompt",),
+    }
+    for relative_path, forbidden_tokens in forbidden_by_source.items():
+        content = (PIPELINE_ROOT / relative_path).read_text(encoding="utf-8")
+        for token in forbidden_tokens:
+            assert token not in content, f"{relative_path} still contains {token}"
+
+
+@pytest.mark.parametrize(
+    ("path", "ordinary_command"),
+    [
+        (REPO_ROOT / "README.md", "python3 ./.prizmkit/dev-pipeline/cli.py run feature F-003"),
+        (
+            REPO_ROOT / "core" / "templates" / "project-memory-template.md",
+            "python3 ./.prizmkit/dev-pipeline/cli.py run <family> <task-id>",
+        ),
+        (
+            REPO_ROOT
+            / "core"
+            / "skills"
+            / "orchestration-skill"
+            / "workflows"
+            / "recovery-workflow"
+            / "SKILL.md",
+            "python3 ./.prizmkit/dev-pipeline/cli.py run feature F-001",
+        ),
+    ],
+)
+def test_canonical_interrupted_task_guidance_uses_recovery_workflow(path, ordinary_command):
+    content = path.read_text(encoding="utf-8")
+
+    assert "recovery-workflow" in content
+    assert ordinary_command in content
+    assert "cli.py recovery" not in content
+
+
 def test_boundary_dataclasses_are_cohesive_and_frozen():
     from prizmkit_runtime.gitops import BranchContext, WorktreePolicy
     from prizmkit_runtime.heartbeat import HeartbeatConfig, HeartbeatState
@@ -1017,6 +1395,31 @@ def test_progress_parser_keeps_pi_length_as_nonfatal_diagnostic_metadata():
     assert data["terminal_success_at"]
 
 
+@pytest.mark.parametrize("role", ("assistant", "toolResult"))
+def test_progress_parser_does_not_promote_pi_diagnostic_content_to_fatal_error(role):
+    module = _load_progress_parser_module()
+    tracker = module.ProgressTracker()
+    tracker.process_event({"type": "session", "version": 3, "id": "pi-session", "cwd": "/tmp/project"})
+    tracker.process_event({"type": "agent_start"})
+    tracker.process_event({
+        "type": "message_end",
+        "message": {
+            "role": role,
+            "content": [{
+                "type": "text",
+                "text": 'continuation_reason = "context_overflow"\nerror = _error_text(result)',
+            }],
+            "stopReason": "toolUse",
+        },
+    })
+
+    data = tracker.to_dict()
+
+    assert data["api_error_code"] == ""
+    assert data["fatal_error_code"] == ""
+    assert data["last_result_is_error"] is False
+
+
 def test_progress_parser_recovers_from_retrying_pi_attempt_before_final_success():
     module = _load_progress_parser_module()
     tracker = module.ProgressTracker()
@@ -1677,6 +2080,57 @@ def test_session_persists_normalized_stream_without_raw_history(tmp_path, monkey
     assert not backup_log.exists()
 
 
+def test_pi_session_diagnostic_tool_output_does_not_trigger_fatal_termination(tmp_path):
+    import prizmkit_runtime.sessions as sessions
+
+    fake_cli = tmp_path / "pi_diagnostic_cli.py"
+    fake_cli.write_text(
+        "#!/usr/bin/env python3\n"
+        "import json, sys, time\n"
+        "_prompt = sys.stdin.read()\n"
+        "source = 'continuation_reason = \\\"context_overflow\\\"\\nerror = _error_text(result)'\n"
+        "events = [\n"
+        " {'type':'session','id':'s1'},\n"
+        " {'type':'agent_start'},\n"
+        " {'type':'turn_start'},\n"
+        " {'type':'tool_execution_start','toolCallId':'c1','toolName':'read','args':{'path':'runtime.py'}},\n"
+        " {'type':'tool_execution_end','toolCallId':'c1','toolName':'read','result':{'content':[{'type':'text','text':source}]},'isError':False},\n"
+        " {'type':'message_end','message':{'role':'toolResult','toolCallId':'c1','content':[{'type':'text','text':source}],'stopReason':'toolUse'}},\n"
+        "]\n"
+        "for event in events: print(json.dumps(event), flush=True)\n"
+        "time.sleep(1.5)\n"
+        "message = {'role':'assistant','content':[{'type':'text','text':'Done'}],'stopReason':'stop'}\n"
+        "print(json.dumps({'type':'message_end','message':message}), flush=True)\n"
+        "print(json.dumps({'type':'agent_end','willRetry':False,'messages':[message]}), 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-diagnostic" / "logs" / "session.log"
+    progress = session_log.with_name("progress.json")
+
+    result = sessions.AISessionLauncher(
+        sessions.AISessionConfig(
+            cli_command=str(fake_cli),
+            platform="pi",
+            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.exit_code == 0
+    assert result.fatal_error_code == ""
+    assert result.progress_summary.result_subtype == "success"
+    assert progress_data["fatal_error_code"] == ""
+    assert not session_log.with_name("fatal-error.json").exists()
+    assert not session_log.with_name("stale-kill.json").exists()
+
+
 def test_custom_session_launch_writes_existing_logs_and_progress(tmp_path):
     from prizmkit_runtime.launch_profiles import HeadlessLaunchProfile
     from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher
@@ -2122,97 +2576,6 @@ def test_compact_live_heartbeat_stays_out_of_primary_and_backup_logs(tmp_path, c
     assert "stale:" not in backup_text.get("content", "")
 
 
-def test_recovery_sessions_receive_live_heartbeat_configuration(tmp_path, monkeypatch):
-    import prizmkit_runtime.runner_recovery as runner_recovery
-
-    project = tmp_path / "project"
-    pipeline = tmp_path / "pipeline"
-    recovery_state = tmp_path / "recovery"
-    project.mkdir()
-    pipeline.mkdir()
-    recovery_state.mkdir()
-    paths = type(
-        "Paths",
-        (),
-        {"project_root": project, "pipeline_root": pipeline, "recovery_state_dir": recovery_state},
-    )()
-    captured_config = {}
-
-    monkeypatch.setattr(
-        runner_recovery,
-        "run_recovery_detect",
-        lambda _paths: (0, "{}", "", {"detected": True, "workflow_type": "feature"}),
-    )
-    monkeypatch.setattr(
-        runner_recovery,
-        "load_runtime_config",
-        lambda _paths: type(
-            "Config",
-            (),
-            {
-                "ai_client": type("Client", (), {"command": "fake-cli", "platform": "codebuddy"})(),
-                "model": "model",
-                "effort": "high",
-            },
-        )(),
-    )
-    monkeypatch.setattr(
-        runner_recovery,
-        "RunnerEnvironment",
-        type(
-            "EnvFactory",
-            (),
-            {
-                "from_env": staticmethod(
-                    lambda: type(
-                        "Env",
-                        (),
-                        {
-                            "verbose": True,
-                            "live_output": True,
-                            "heartbeat_interval_seconds": 7,
-                            "heartbeat_stale_threshold_seconds": 21,
-                            "stale_kill_threshold_seconds": 42,
-                        },
-                    )()
-                )
-            },
-        ),
-    )
-    monkeypatch.setattr(runner_recovery, "detect_stream_json_support", lambda *_args: type("Support", (), {"enabled": True})())
-    monkeypatch.setattr(
-        runner_recovery.subprocess,
-        "run",
-        lambda *_args, **_kwargs: type("Completed", (), {"returncode": 0, "stdout": "0", "stderr": ""})(),
-    )
-    monkeypatch.setattr(runner_recovery, "_recovery_outcome", lambda *_args, **_kwargs: ("no_changes", {}))
-
-    class FakeLauncher:
-        def __init__(self, config):
-            captured_config["config"] = config
-
-        def run(self):
-            return type("Result", (), {"exit_code": 0})()
-
-    monkeypatch.setattr(runner_recovery, "AISessionLauncher", FakeLauncher)
-
-    code, stdout, stderr = runner_recovery.run_recovery(paths)
-    config = captured_config["config"]
-
-    assert code == 0
-    assert stdout == "no_changes\n"
-    assert stderr == ""
-    assert config.live_output is True
-    assert config.verbose is True
-    assert config.use_stream_json is True
-    assert config.live_progress_interval_seconds == 7
-    assert config.heartbeat_stale_threshold_seconds == 21
-    assert config.stale_kill_threshold_seconds == 42
-    assert config.live_banner is False
-    assert config.suppress_stream_output is True
-
-
-
 def test_session_summary_reports_normalized_subagents_and_child_liveness(tmp_path, capsys):
     import prizmkit_runtime.runners as runners
     from prizmkit_runtime.runner_models import SessionPaths