prizmkit 1.1.153 → 1.1.155

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,76 +477,131 @@ 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",
+        "--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"))
+    assert runtime_cli.main(["daemon", "feature", "start"]) == 0
+    assert captured[-1] == ("daemon", "start", "feature", ())
 
     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"))
 
-    assert runtime_cli.main(["--project-root", "feature", "feature", "describe"]) == 0
-    assert captured[-1] == ("feature", "describe", None, ())
+    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")
+    )
 
+    interspersed_daemon = ["daemon", "feature", "start", "custom.json"]
+    assert runtime_cli.main(interspersed_daemon) == 0
+    assert captured[-1] == (
+        "daemon", "start", "feature", ("custom.json",)
+    )
 
-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
+    assert runtime_cli.main(["--project-root", "feature", "run", "feature", "--dry-run"]) == 0
+    assert captured[-1] == ("run", "run", "feature", ("--dry-run",))
+
+
+def test_pipeline_mode_option_is_rejected():
+    foreground = run_cli("run", "feature", "--mode", "full")
+    daemon = run_cli("daemon", "feature", "start", "--mode", "full")
+
+    assert foreground.returncode == 2
+    assert daemon.returncode == 2
+    assert "unrecognized arguments" in foreground.stderr
+    assert "unrecognized arguments" in daemon.stderr
 
-    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", ("--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 +614,203 @@ 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 _write_family_runtime_status(paths, family, task_id):
+    state_dir = {
+        "feature": paths.feature_state_dir,
+        "bugfix": paths.bugfix_state_dir,
+        "refactor": paths.refactor_state_dir,
+    }[family]
+    status_path = state_dir / task_id / "status.json"
+    status_path.parent.mkdir(parents=True, exist_ok=True)
+    status_path.write_text(
+        json.dumps(
+            {
+                {
+                    "feature": "feature_id",
+                    "bugfix": "bug_id",
+                    "refactor": "refactor_id",
+                }[family]: task_id,
+                "retry_count": 0,
+                "sessions": [],
+                "resume_from_phase": 9,
+            }
+        ),
+        encoding="utf-8",
+    )
+    return status_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)
+    configured = {
+        "feature": "F-001",
+        "bugfix": "B-001",
+        "refactor": "R-001",
+    }
+    for family, task_id in configured.items():
+        _write_family_status_plan(paths, family, task_id)
+        _write_family_runtime_status(paths, family, task_id)
+    before = _file_bytes_under(tmp_path)
+
+    result = run_cli("--project-root", str(tmp_path), "status", "all")
+
+    assert result.returncode == 0, result.stderr
+    assert "FEATURE\n=======" in result.stdout
+    assert "Python feature status" in result.stdout
+    assert "BUGFIX\n======" in result.stdout
+    assert "Python bugfix status" in result.stdout
+    assert "REFACTOR\n========" in result.stdout
+    assert "Python refactor status" in result.stdout
+    assert _file_bytes_under(tmp_path) == before
+
+
+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 +846,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
@@ -876,7 +1287,7 @@ def test_session_preamble_writes_redacted_start_command_for_all_launch_profiles(
             assert str(prompt) not in "\n".join(lines[:6])
 
 
-def test_headless_review_guidance_defers_to_skill_review_contract():
+def test_headless_review_guidance_maps_stage_local_skill_result():
     headless_guidance_files = [
         REPO_ROOT / "dev-pipeline" / "templates" / "sections" / "phase-review-full.md",
         REPO_ROOT / "dev-pipeline" / "templates" / "bootstrap-tier3.md",
@@ -892,9 +1303,10 @@ def test_headless_review_guidance_defers_to_skill_review_contract():
 
     for path in headless_guidance_files:
         text = path.read_text(encoding="utf-8")
-        assert "current review contract" in text, path
-        assert "second review path outside that contract" in text, path
+        assert "returns only `PASS` or `NEEDS_FIXES`" in text, path
+        assert "this injected session" in text, path
         assert "text final-verdict" in text, path
+        assert "follow the skill's current review contract" not in text, path
         assert "low=0" not in text and "Reviewer 3" not in text, path
         assert "forced-worktree changed-content fallback" not in text, path
         assert "isolation:" not in text, path
@@ -2198,97 +2610,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
@@ -2773,6 +3094,60 @@ def test_branch_merge_preserves_preexisting_stash_when_workspace_is_clean(tmp_pa
     assert (tmp_path / "feature.txt").read_text(encoding="utf-8") == "done\n"
 
 
+def test_branch_merge_fast_forwards_with_dirty_prizmkit_internal_state(tmp_path):
+    from prizmkit_runtime.gitops import (
+        BranchContext,
+        branch_fast_forward_possible,
+        branch_merge_plan,
+        run_git_plan,
+    )
+
+    _init_merge_repo(tmp_path)
+    context = BranchContext("main", "dev/example", tmp_path)
+    subprocess.run(
+        ["git", "checkout", "-b", context.working_branch],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.DEVNULL,
+    )
+    (tmp_path / "feature.txt").write_text("done\n", encoding="utf-8")
+    subprocess.run(["git", "add", "feature.txt"], cwd=tmp_path, check=True)
+    subprocess.run(
+        ["git", "commit", "-m", "feature"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.DEVNULL,
+    )
+    manifest = tmp_path / ".prizmkit" / "manifest.json"
+    manifest.write_text('{"version":"session-local"}\n', encoding="utf-8")
+
+    assert branch_fast_forward_possible(tmp_path, context) is True
+    result = run_git_plan(
+        tmp_path,
+        branch_merge_plan(context, rebase=False),
+    )
+
+    assert result.ok is True
+    assert not any(command.args and command.args[0] == "rebase" for command in result.plan.commands)
+    assert subprocess.run(
+        ["git", "branch", "--show-current"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout.strip() == "main"
+    assert (tmp_path / "feature.txt").read_text(encoding="utf-8") == "done\n"
+    assert json.loads(manifest.read_text(encoding="utf-8"))["version"] == "session-local"
+    assert ".prizmkit/manifest.json" in subprocess.run(
+        ["git", "status", "--short"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout
+    assert _stash_oids(tmp_path) == ()
+
+
 def test_branch_merge_rejects_dirty_task_checkout_without_touching_stashes(tmp_path):
     from prizmkit_runtime.gitops import BranchContext, branch_merge_plan, run_git_plan
 
@@ -3507,6 +3882,60 @@ def test_materialize_worktree_support_assets_copies_ignored_assets_without_retir
     assert guarded_worktree_remove(runtime, delete_branch=False).ok
 
 
+def test_linked_worktree_fast_forwards_with_dirty_prizmkit_internal_state(tmp_path):
+    from prizmkit_runtime.gitops import (
+        BranchContext,
+        WorktreePolicy,
+        branch_fast_forward_possible,
+        ensure_linked_worktree,
+        guarded_worktree_remove,
+        merge_linked_worktree,
+        worktree_runtime_context,
+    )
+
+    repo = tmp_path / "repo"
+    _init_temp_repo(repo)
+    config = repo / ".prizmkit" / "config.json"
+    config.parent.mkdir(parents=True)
+    config.write_text('{"mode":"base"}\n', encoding="utf-8")
+    subprocess.run(["git", "add", ".prizmkit/config.json"], cwd=repo, check=True)
+    subprocess.run(
+        ["git", "commit", "-m", "track internal config"],
+        cwd=repo,
+        check=True,
+        stdout=subprocess.DEVNULL,
+    )
+    runtime = worktree_runtime_context(
+        BranchContext("main", "dev/internal-dirt", repo),
+        WorktreePolicy(
+            True,
+            cleanup_on_success=True,
+            preserve_on_failure=True,
+            worktree_root=tmp_path / "worktrees",
+        ),
+    )
+    assert ensure_linked_worktree(runtime).ok
+    (runtime.worktree_path / "feature.txt").write_text("done\n", encoding="utf-8")
+    subprocess.run(["git", "add", "feature.txt"], cwd=runtime.worktree_path, check=True)
+    subprocess.run(
+        ["git", "commit", "-m", "feature"],
+        cwd=runtime.worktree_path,
+        check=True,
+        stdout=subprocess.DEVNULL,
+    )
+    worktree_config = runtime.worktree_path / ".prizmkit" / "config.json"
+    worktree_config.write_text('{"mode":"session-local"}\n', encoding="utf-8")
+
+    assert branch_fast_forward_possible(repo, runtime.context) is True
+    result = merge_linked_worktree(runtime)
+
+    assert result.ok is True
+    assert not any(item.args and item.args[0] == "rebase" for item in result.results)
+    assert (repo / "feature.txt").read_text(encoding="utf-8") == "done\n"
+    assert json.loads(worktree_config.read_text(encoding="utf-8"))["mode"] == "session-local"
+    assert guarded_worktree_remove(runtime, delete_branch=True).ok
+
+
 def test_worktree_terminal_failure_wip_commit_preserves_dirty_changes_before_cleanup(tmp_path):
     from prizmkit_runtime.gitops import (
         BranchContext,
@@ -3588,9 +4017,9 @@ def test_checkpoint_rewind_preserves_planning_and_resets_implementation_downstre
         "prizmkit-implement",
         "prizmkit-code-review",
         "prizmkit-test",
+        "completion-summary",
         "prizmkit-retrospective",
         "prizmkit-committer",
-        "completion-summary",
     ]
     steps = []
     previous = None
@@ -3622,7 +4051,7 @@ def test_checkpoint_rewind_preserves_planning_and_resets_implementation_downstre
         "feature_state": {
             "schema_version": 1,
             "artifact_dir": ".prizmkit/specs/example",
-            "orchestrator": "prizmkit-l4",
+            "orchestrator": "pipeline-runtime",
             "stage": "code-review",
             "current_stage": "prizmkit-code-review",
             "status": "failed",