prizmkit 1.1.107 → 1.1.109

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

@@ -7,7 +7,6 @@ from continuation import append_continuation_handoff
 from generate_refactor_prompt import (
     build_replacements,
     generate_refactor_checkpoint,
-    load_log_size_section,
     merge_refactor_checkpoint_state,
 )
 
@@ -35,7 +34,7 @@ class TestRefactorContinuationHandoff:
 
         assert prompt.startswith("REFACTOR PROMPT")
         assert "This is a fresh headless AI CLI session for the same task." in prompt
-        assert "Do not attempt `/compact` as the recovery mechanism." in prompt
+        assert "Do not attempt `/compact` as the recovery mechanism." not in prompt
         assert ("Log " + "monitor") not in prompt
         assert ("log-" + "monitor") not in prompt
         assert (tmp_path / ".prizmkit/specs/R-007/continuation-summary.md").exists()
@@ -54,19 +53,103 @@ class TestRefactorCheckpointMerge:
         assert merged["steps"][1]["status"] == "pending"
 
 
+class TestExplicitProjectRoot:
+    def test_build_replacements_infers_project_root_from_refactor_list(self, tmp_path, monkeypatch):
+        monkeypatch.delenv("PRIZMKIT_PLATFORM", raising=False)
+        project = tmp_path / "project"
+        plan_path = project / ".prizmkit" / "plans" / "refactor-list.json"
+        plan_path.parent.mkdir(parents=True)
+        (project / ".prizmkit" / "config.json").write_text(
+            '{"platform":"claude","ai_cli":"claude"}', encoding="utf-8"
+        )
+        args = Namespace(
+            refactor_list=str(plan_path),
+            refactor_id="R-001",
+            session_id="session-1",
+            run_id="run-1",
+            retry_count="0",
+            resume_phase="null",
+            state_dir=str(project / ".prizmkit" / "state" / "refactor"),
+            output=str(project / "out.md"),
+            template=None,
+            mode=None,
+            critic=None,
+        )
+        refactor = {"id": "R-001", "title": "Restructure", "description": "d"}
+
+        replacements = build_replacements(
+            args, refactor, [refactor], {}, str(Path("dev-pipeline/scripts").resolve())
+        )
+
+        assert replacements["{{PROJECT_ROOT}}"] == str(project.resolve())
+        assert replacements["{{REVIEWER_SUBAGENT_PATH}}"].endswith(
+            ".claude/agents/prizm-dev-team-reviewer.md"
+        )
+        assert replacements["{{REVIEWER_SUBAGENT_PATH}}"].startswith(str(project.resolve()))
+        assert replacements["{{SESSION_STATUS_PATH}}"] == str(
+            project / ".prizmkit" / "state" / "refactor" / "R-001" /
+            "sessions" / "session-1" / "session-status.json"
+        )
+
+    def test_build_replacements_uses_cli_project_root_for_rendered_paths(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("PRIZMKIT_PLATFORM", "claude")
+        execution_root = tmp_path / "worktree"
+        main_checkout = tmp_path / "main"
+        execution_root.mkdir()
+        main_checkout.mkdir()
+        args = Namespace(
+            refactor_list=str(main_checkout / ".prizmkit" / "plans" / "refactor-list.json"),
+            refactor_id="R-001",
+            session_id="session-1",
+            run_id="run-1",
+            retry_count="0",
+            resume_phase="null",
+            state_dir=str(main_checkout / ".prizmkit" / "state" / "refactor"),
+            output=str(main_checkout / ".prizmkit" / "state" / "refactor" / "R-001" / "sessions" / "session-1" / "bootstrap-prompt.md"),
+            template=None,
+            mode=None,
+            critic=None,
+            project_root=str(execution_root),
+        )
+        refactor = {"id": "R-001", "title": "Worktree Refactor", "description": "d"}
+
+        replacements = build_replacements(
+            args,
+            refactor,
+            [refactor],
+            {},
+            str(main_checkout / "dev-pipeline" / "scripts"),
+        )
+
+        assert replacements["{{PROJECT_ROOT}}"] == str(execution_root.resolve())
+        assert replacements["{{SESSION_STATUS_PATH}}"] == str(
+            main_checkout / ".prizmkit" / "state" / "refactor" / "R-001" /
+            "sessions" / "session-1" / "session-status.json"
+        )
+        assert not replacements["{{SESSION_STATUS_PATH}}"].startswith(str(execution_root.resolve()))
+        assert replacements["{{DEV_SUBAGENT_PATH}}"].startswith(str(execution_root.resolve()))
+        assert "### Checkpoint Update Helper" in replacements["{{CHECKPOINT_SYSTEM}}"]
+        assert "{{CHECKPOINT_PYTHON_CMD}}" in replacements["{{CHECKPOINT_SYSTEM}}"]
+        assert "pipeline progress mechanism" not in replacements["{{CHECKPOINT_SYSTEM}}"]
+        assert "prizmkit-runtime-helper.py" in replacements["{{RUNTIME_HELPER_CMD}}"]
+
+
 class TestRefactorPromptMaxLogRemoval:
-    def test_refactor_log_size_section_is_checkpoint_guidance_without_max_log_env(self):
-        content = load_log_size_section(str(Path("dev-pipeline/scripts").resolve()))
-
-        assert "passive checkpoint guidance" in content
-        assert "Headless recovery must rely on durable checkpoints" in content
-        assert "fresh continuation session" in content
-        assert REMOVED_MAX_LOG_ENV not in content
-        assert REMOVED_MAX_LOG_HUMAN not in content
-        assert ("maximum-" + "log-size") not in content
-        assert ("log size " + "limit") not in content.lower()
-
-    def test_refactor_replacements_keep_session_log_without_max_log_placeholders(self):
+    def test_refactor_source_has_no_deleted_log_size_injection(self):
+        deleted_section = "log-size-" + "awareness.md"
+        loader = "load_" + "log_size_section"
+        placeholder = "{{LOG_" + "SIZE_AWARENESS}}"
+        deleted_title = "Session " + "Checkpoint Awareness"
+        source = Path("dev-pipeline/scripts/generate-refactor-prompt.py").read_text(encoding="utf-8")
+        template = Path("dev-pipeline/templates/refactor-bootstrap-prompt.md").read_text(encoding="utf-8")
+
+        assert (Path("dev-pipeline/templates/sections") / deleted_section).exists() is False
+        for content in (source, template):
+            for forbidden in (deleted_section, loader, placeholder, deleted_title):
+                assert forbidden not in content
+
+    def test_refactor_replacements_keep_session_log_without_max_log_placeholders(self, monkeypatch):
+        monkeypatch.setenv("PRIZMKIT_PLATFORM", "claude")
         args = Namespace(
             refactor_id="R-001",
             session_id="session-1",
@@ -90,3 +173,24 @@ class TestRefactorPromptMaxLogRemoval:
         )
         assert "{{" + REMOVED_MAX_LOG_ENV + "}}" not in replacements
         assert "{{" + REMOVED_MAX_LOG_HUMAN + "}}" not in replacements
+        assert "{{LOG_" + "SIZE_AWARENESS}}" not in replacements
+
+
+HEADLESS_FORBIDDEN_PROMPT_STRINGS = [
+    "### Interactive Claude Code Note",
+    "### Project Conventions",
+    "Scaffold / generated file awareness",
+    "### Resume Behavior",
+    "[NEEDS CLARIFICATION]",
+    "pause for interactive input",
+    "prizmkit-test-gate.py",
+    "/compact",
+    "Session " + "Checkpoint Awareness",
+    "{{LOG_" + "SIZE_AWARENESS}}",
+]
+
+
+def test_template_source_is_clean_for_headless_prompt_contract():
+    content = Path("dev-pipeline/templates/refactor-bootstrap-prompt.md").read_text(encoding="utf-8")
+    for forbidden in HEADLESS_FORBIDDEN_PROMPT_STRINGS:
+        assert forbidden not in content

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

@@ -604,6 +604,7 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
 
     prompt_calls = []
     launch_cwds = []
+    launch_configs = []
     updates = []
     cleanup_calls = []
     merge_calls = []
@@ -621,6 +622,7 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
     )
     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_preflight_ready_changes", lambda *args, **kwargs: SimpleNamespace(attempted=False, committed=False, ok=True, result=None))
     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")
@@ -652,6 +654,7 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
 
         def run(self):
             launch_cwds.append(self.config.cwd)
+            launch_configs.append(self.config)
             return SimpleNamespace(progress_summary=SimpleNamespace(), fatal_error_code="")
 
     def fake_classify(*args, **kwargs):
@@ -690,6 +693,7 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
     return SimpleNamespace(
         prompt_calls=prompt_calls,
         launch_cwds=launch_cwds,
+        launch_configs=launch_configs,
         updates=updates,
         cleanup_calls=cleanup_calls,
         merge_calls=merge_calls,
@@ -697,6 +701,36 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
     )
 
 
+
+def test_runner_launch_config_preserves_artifact_paths_live_output_and_split_thresholds(monkeypatch, tmp_path):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    monkeypatch.setenv("PRIZMKIT_LIVE_OUTPUT", "0")
+    monkeypatch.setenv("HEARTBEAT_INTERVAL", "7")
+    monkeypatch.setenv("HEARTBEAT_STALE_THRESHOLD", "11")
+    monkeypatch.setenv("STALE_KILL_THRESHOLD", "13")
+    paths = _make_paths(tmp_path / "artifact-wiring")
+    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, "run_git_plan", lambda *args, **kwargs: SimpleNamespace(ok=True, reason="", results=()))
+
+    status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
+
+    config = observed.launch_configs[0]
+    expected_log = paths.feature_state_dir / "F-001" / "sessions" / "F-001-session-1" / "logs" / "session.log"
+    assert status == "completed"
+    assert config.live_output is False
+    assert config.live_progress_interval_seconds == 7
+    assert config.heartbeat_stale_threshold_seconds == 11
+    assert config.stale_kill_threshold_seconds == 13
+    assert config.log_path == expected_log
+    assert config.progress_path == expected_log.with_name("progress.json")
+    assert config.heartbeat_path == expected_log.with_name("heartbeat.json")
+
+
 @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_explicit_worktree_launches_from_worktree_and_renders_worktree_root(monkeypatch, tmp_path, kind, item_id, branch):
     from prizmkit_runtime import runners
@@ -710,18 +744,26 @@ def test_feature_and_bugfix_explicit_worktree_launches_from_worktree_and_renders
     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 = []
+    lifecycle_order = []
 
     def fake_setup(runtime):
+        lifecycle_order.append("worktree_setup")
         setup_calls.append(runtime)
         runtime.worktree_path.mkdir(parents=True, exist_ok=True)
         return SimpleNamespace(ok=True, runtime=runtime, reason="")
 
+    def fake_preflight(*args, **kwargs):
+        lifecycle_order.append("preflight")
+        return SimpleNamespace(attempted=False, committed=False, ok=True, result=None)
+
+    monkeypatch.setattr(runners, "commit_preflight_ready_changes", fake_preflight)
     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 lifecycle_order[:2] == ["preflight", "worktree_setup"]
     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
@@ -842,6 +884,7 @@ def test_explicit_worktree_materializes_ignored_support_assets_before_prompt_and
     )
     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_preflight_ready_changes", lambda *args, **kwargs: SimpleNamespace(attempted=False, committed=False, ok=True, result=None))
     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")
@@ -921,6 +964,11 @@ def test_default_no_worktree_preserves_main_worktree_branch_launch(monkeypatch,
         lifecycle_order.append("start_item")
         return SimpleNamespace(ok=True, text="", data={"new_status": "in_progress"})
 
+    def fake_preflight(*args, **kwargs):
+        lifecycle_order.append("preflight")
+        return SimpleNamespace(attempted=False, committed=False, ok=True, result=None)
+
+    monkeypatch.setattr(runners, "commit_preflight_ready_changes", fake_preflight)
     monkeypatch.setattr(runners, "run_git_plan", fake_run_git_plan)
     monkeypatch.setattr(runners, "start_item", fake_start_item)
     monkeypatch.setattr(runners, "ensure_linked_worktree", lambda runtime: (_ for _ in ()).throw(AssertionError("worktree setup should not run")), raising=False)
@@ -932,7 +980,7 @@ def test_default_no_worktree_preserves_main_worktree_branch_launch(monkeypatch,
     assert observed.prompt_calls[0].get("execution_root") == paths.project_root
     assert "branch_create" in plan_names
     assert "branch_merge" in plan_names
-    assert lifecycle_order[:2] == ["branch_create", "start_item"]
+    assert lifecycle_order[:3] == ["preflight", "branch_create", "start_item"]
     assert branch_events == [("create", "dev/F-001-test"), ("merge", "dev/F-001-test")]
 
 
@@ -1024,6 +1072,7 @@ def test_no_worktree_recovers_completed_pending_branch_before_new_session(monkey
     monkeypatch.setattr(runners, "has_branch_completion_evidence", lambda *args, **kwargs: True)
     monkeypatch.setattr(runners, "commit_final_bookkeeping", lambda *args, **kwargs: None)
     monkeypatch.setattr(runners, "commit_task_branch_changes", lambda *args, **kwargs: None)
+    monkeypatch.setattr(runners, "commit_preflight_ready_changes", lambda *args, **kwargs: SimpleNamespace(attempted=False, committed=False, ok=True, result=None))
 
     def fake_update(family, invocation, item_id, session_status, session_id, project_root, **metadata):
         updates.append((session_status, session_id, metadata))
@@ -1076,6 +1125,7 @@ def test_worktree_recovers_completed_pending_branch_from_base_session_history(mo
     monkeypatch.setattr(runners, "generate_prompt", lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("should not launch prompt")))
     monkeypatch.setattr(runners, "commit_final_bookkeeping", lambda *args, **kwargs: None)
     monkeypatch.setattr(runners, "commit_task_branch_changes", lambda *args, **kwargs: None)
+    monkeypatch.setattr(runners, "commit_preflight_ready_changes", lambda *args, **kwargs: SimpleNamespace(attempted=False, committed=False, ok=True, result=None))
 
     def fake_update(family, invocation, item_id, session_status, session_id, project_root, **metadata):
         updates.append((session_status, session_id, project_root, metadata))
@@ -1187,6 +1237,33 @@ def test_no_worktree_runner_ignores_recovery_side_effect_branch(monkeypatch, tmp
     assert observed.updates[-1][2]["base_branch"] == "main"
 
 
+def test_no_worktree_preflight_commit_failure_aborts_before_branch_or_status(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-preflight-fail")
+    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})
+    events = []
+
+    monkeypatch.setattr(
+        runners,
+        "load_runtime_config",
+        lambda paths: SimpleNamespace(ai_client=SimpleNamespace(command="fake-ai", platform="codebuddy"), model="", effort=None),
+    )
+    monkeypatch.setattr(runners, "current_branch", lambda _root: "main")
+    monkeypatch.setattr(runners, "commit_preflight_ready_changes", lambda *args, **kwargs: SimpleNamespace(attempted=True, committed=False, result=SimpleNamespace(stderr="commit failed\n", stdout="")))
+    monkeypatch.setattr(runners, "run_git_plan", lambda *args, **kwargs: events.append("branch_create"))
+    monkeypatch.setattr(runners, "start_item", lambda *args, **kwargs: events.append("start_item"))
+
+    with pytest.raises(RuntimeError, match="Preflight dirty workspace preservation failed"):
+        runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
+
+    assert events == []
+
+
 def test_foreground_runner_emits_structured_feature_progress(monkeypatch, tmp_path, capsys):
     from prizmkit_runtime import runners
     from prizmkit_runtime.runner_models import family_for, parse_invocation
@@ -1212,7 +1289,7 @@ def test_foreground_runner_emits_structured_feature_progress(monkeypatch, tmp_pa
     assert "────────────────────────────────────────────────────" in captured.err
     assert "Feature: F-001 — Readable output" in captured.err
     assert "Code retry: 1 / 3" in captured.err
-    assert "Infrastructure retry: 2 / 3" in captured.err
+    assert "Preflight: no user-visible changes to preserve before feature task F-001" in captured.err
     assert "Pipeline mode: lite (Tier 1 — Single Agent)" in captured.err
     assert "Agents: 1 (critic: disabled)" in captured.err
     assert "Spawning AI CLI session: F-001-session-1" in captured.err

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

@@ -0,0 +1,211 @@
+"""Tests for the cross-platform prompt runtime helper CLI."""
+
+import json
+import os
+import socket
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PIPELINE_ROOT = REPO_ROOT / "dev-pipeline"
+HELPER_SCRIPT = PIPELINE_ROOT / "scripts" / "prizmkit-runtime-helper.py"
+CLI_PATH = PIPELINE_ROOT / "cli.py"
+
+if str(PIPELINE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PIPELINE_ROOT))
+
+
+def run_helper(*args, cwd=None):
+    return subprocess.run(
+        [sys.executable, str(HELPER_SCRIPT), *args],
+        cwd=cwd or REPO_ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+
+
+def first_line(result):
+    return result.stdout.splitlines()[0]
+
+
+class TestArtifactAndTextHelpers:
+    def test_exists_ensure_dir_touch_list_tree_and_source_files(self, tmp_path):
+        missing = run_helper("artifact", "exists", str(tmp_path / "missing"))
+        assert first_line(missing) == "MISSING"
+
+        ready = run_helper("artifact", "ensure-dir", str(tmp_path / "src"))
+        assert first_line(ready) == "DIR_READY"
+        touched = run_helper("artifact", "touch", str(tmp_path / "src" / "app.py"))
+        assert first_line(touched) == "TOUCHED"
+        (tmp_path / "src" / "README.md").write_text("hello helper\n", encoding="utf-8")
+        (tmp_path / "src" / "ignored.bin").write_bytes(b"\x00")
+
+        listing = run_helper("artifact", "list", str(tmp_path / "src"))
+        assert first_line(listing) == "LIST"
+        assert "file:README.md" in listing.stdout
+        assert "file:app.py" in listing.stdout
+
+        tree = run_helper("artifact", "tree", str(tmp_path), "--max-depth", "2")
+        assert first_line(tree) == "TREE"
+        assert "entry: src/" in tree.stdout
+        assert "entry: src/app.py" in tree.stdout
+
+        sources = run_helper("artifact", "source-files", str(tmp_path), "--ext", ".py", "--json")
+        payload = json.loads(sources.stdout)
+        assert payload["marker"] == "SOURCE_FILES"
+        assert payload["files"] == ["src/app.py"]
+
+    def test_text_search_count_and_contains_markers(self, tmp_path):
+        target = tmp_path / "notes.md"
+        target.write_text("alpha\nbeta alpha\n", encoding="utf-8")
+
+        search = run_helper("text", "search", str(tmp_path), "--pattern", "alpha")
+        assert first_line(search) == "FOUND"
+        assert "count: 2" in search.stdout
+
+        count = run_helper("text", "count", str(tmp_path), "--pattern", "alpha")
+        assert first_line(count) == "COUNT"
+        assert "count: 2" in count.stdout
+
+        contains = run_helper("text", "contains", str(target), "--pattern", "beta")
+        assert first_line(contains) == "GATE:PASS"
+        missing = run_helper("text", "contains", str(target), "--pattern", "gamma")
+        assert first_line(missing) == "GATE:MISSING"
+
+
+class TestPlatformExecutableAndPortHelpers:
+    def test_platform_detection_and_skill_lookup_follow_config(self, tmp_path, monkeypatch):
+        project = tmp_path / "project"
+        skill_dir = project / ".agents" / "skills" / "playwright-cli"
+        skill_dir.mkdir(parents=True)
+        (project / ".prizmkit").mkdir()
+        (project / ".prizmkit" / "config.json").write_text(
+            json.dumps({"platform": "codex", "ai_cli": "codex"}), encoding="utf-8"
+        )
+        monkeypatch.delenv("PRIZMKIT_PLATFORM", raising=False)
+
+        detect = run_helper("platform", "detect", "--project-root", str(project), "--json")
+        payload = json.loads(detect.stdout)
+        assert payload["marker"] == "CODEX"
+        assert payload["platform"] == "codex"
+        assert payload["source"] == "config:ai_cli"
+
+        skill = run_helper("platform", "skill", "playwright-cli", "--project-root", str(project), "--json")
+        payload = json.loads(skill.stdout)
+        assert payload["marker"] == "SKILL_EXISTS"
+        assert payload["platform"] == "codex"
+        assert payload["path"].endswith(".agents/skills/playwright-cli")
+
+    def test_codebuddy_cli_env_wins_over_filesystem_markers(self, tmp_path, monkeypatch):
+        from prizmkit_runtime.platform_detection import resolve_platform
+
+        project = tmp_path / "project"
+        (project / ".claude" / "agents").mkdir(parents=True)
+        monkeypatch.delenv("PRIZMKIT_PLATFORM", raising=False)
+        resolution = resolve_platform(project, env={"CODEBUDDY_CLI": "cbc"})
+
+        assert resolution.platform == "codebuddy"
+        assert resolution.source == "environment:CODEBUDDY_CLI"
+
+    def test_executable_check_and_version_use_shutil_and_direct_subprocess(self, tmp_path):
+        executable = tmp_path / "tool.py"
+        executable.write_text("#!/usr/bin/env python3\nprint('tool 1.2.3')\n", encoding="utf-8")
+        executable.chmod(0o755)
+        env_path = f"{tmp_path}{os.pathsep}{os.environ.get('PATH', '')}"
+
+        result = subprocess.run(
+            [sys.executable, str(HELPER_SCRIPT), "executable", "check", "tool.py"],
+            env={**os.environ, "PATH": env_path},
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+        assert first_line(result) == "INSTALLED"
+
+        version = subprocess.run(
+            [sys.executable, str(HELPER_SCRIPT), "executable", "version", "tool.py", "--arg=--version"],
+            env={**os.environ, "PATH": env_path},
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+        assert first_line(version) == "VERSION"
+        assert "version: tool 1.2.3" in version.stdout
+
+    def test_port_check_reports_free_and_in_use(self):
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.bind(("127.0.0.1", 0))
+        sock.listen(1)
+        port = sock.getsockname()[1]
+        try:
+            in_use = run_helper("port", "check", str(port))
+            assert first_line(in_use) == "PORT_IN_USE"
+        finally:
+            sock.close()
+        free = run_helper("port", "check", str(port))
+        assert first_line(free) == "PORT_FREE"
+
+
+class TestProcessAndEntrypointHelpers:
+    def test_process_start_status_and_cleanup(self, tmp_path):
+        sleeper = tmp_path / "sleep.py"
+        sleeper.write_text("import time\ntime.sleep(30)\n", encoding="utf-8")
+        pid_file = tmp_path / "server.pid"
+
+        start = run_helper(
+            "process",
+            "start",
+            "--pid-file",
+            str(pid_file),
+            "--",
+            sys.executable,
+            str(sleeper),
+        )
+        assert first_line(start) == "PROCESS_STARTED"
+        pid = int(pid_file.read_text(encoding="utf-8").strip())
+
+        status = run_helper("process", "status-pid", str(pid))
+        assert first_line(status) == "PROCESS_RUNNING"
+
+        cleanup = run_helper("process", "cleanup-pid", str(pid), "--grace-seconds", "0.2")
+        assert first_line(cleanup) in {"PROCESS_TERMINATED", "PROCESS_NOT_RUNNING"}
+
+    def test_cleanup_port_is_deterministic_without_lsof(self):
+        result = run_helper("process", "cleanup-port", "9")
+        assert first_line(result) in {"PORT_FREE", "UNSUPPORTED"}
+        assert "lsof" not in result.stdout.lower()
+
+    def test_canonical_cli_exposes_helper_group(self, tmp_path):
+        existing = tmp_path / "exists.txt"
+        existing.write_text("ok", encoding="utf-8")
+        result = subprocess.run(
+            [sys.executable, str(CLI_PATH), "helper", "artifact", "exists", str(existing)],
+            cwd=REPO_ROOT,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+        assert result.returncode == 0
+        assert first_line(result) == "EXISTS"
+
+    def test_web_wait_ready_accepts_local_http_server(self, tmp_path):
+        server = tmp_path / "server.py"
+        server.write_text(
+            "from http.server import HTTPServer, BaseHTTPRequestHandler\n"
+            "class H(BaseHTTPRequestHandler):\n"
+            "    def do_GET(self):\n"
+            "        self.send_response(200); self.end_headers(); self.wfile.write(b'ok')\n"
+            "    def log_message(self, *args): pass\n"
+            "HTTPServer(('127.0.0.1', 0), H).serve_forever()\n",
+            encoding="utf-8",
+        )
+        # Use helper process start for coverage, then skip fixed URL because the
+        # child selects an ephemeral port that is not externally reported.
+        result = run_helper("web", "wait-ready", "--url", "http://127.0.0.1:9", "--timeout", "0.1", "--interval", "0.05")
+        assert first_line(result) == "NOT_READY"