prizmkit 1.1.108 → 1.1.110

package/bundled/dev-pipeline/templates/sections/phase-review-full.md

@@ -9,7 +9,7 @@ The skill runs an internal review-fix loop (Reviewer Agent → filter → orches
 **Gate Check — Review Report**:
 After `/prizmkit-code-review` returns, verify the review report:
 ```bash
-grep -q "## Verdict" .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
+{{RUNTIME_HELPER_CMD}} text contains .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md --pattern "## Verdict"
 ```
 If GATE:MISSING:
 - Do not re-run `/prizmkit-code-review` in an unbounded report-repair loop.

package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md

@@ -2,7 +2,7 @@
 
 Check existing artifacts first:
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}
 ```
 
 - Both (spec.md, plan.md) exist → **SKIP to CP-1**
@@ -12,11 +12,11 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 **Step A — Build Context Snapshot** (skip if `context-snapshot.md` already exists):
 
 1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 prizm docs
-2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
+2. Detect source code directories from KEY_FILES and STRUCTURE sections in `root.prizm`; if root docs are unavailable, use the helper to list likely source files:
    ```bash
-   find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
+   {{RUNTIME_HELPER_CMD}} artifact source-files . --json
    ```
-   Identify the top-level source directories from the results.
+   Identify the top-level source directories from the helper output.
 3. Scan the detected source directories for files related to this feature; read each one
 4. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description (copy from Task Contract above, 2-3 lines only)
@@ -35,14 +35,15 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 
      ### Known TRAPS (from .prizmkit/prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
-5. Confirm: `ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
+5. Confirm: `{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
 
 **After Step A**: Use context-snapshot.md Section 4 File Manifest to guide targeted file reads. Do NOT scan directories or read unrelated files.
 
 **Step B — Planning Artifacts** (generate only missing files):
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/spec.md .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/spec.md
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/plan.md
 ```
 
 - spec.md missing: Run `/prizmkit-plan` → generate spec.md. Resolve uncertain requirements from the task description, existing code, and conservative existing-project patterns.

package/bundled/dev-pipeline/templates/sections/phase0-init.md

@@ -1,6 +1,6 @@
 ### Phase 0: Project Bootstrap
 - Run `/prizmkit-init` (invoke the prizmkit-init skill)
-- Run `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
+- Run `{{PYTHON_CMD}} {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
 - **CP-0**: Verify `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json` exist
 
 

package/bundled/dev-pipeline/templates/sections/subagent-timeout-recovery.md

@@ -1,6 +1,6 @@
 ## Subagent Timeout Recovery
 
 If any agent times out:
-1. `ls .prizmkit/specs/{{FEATURE_SLUG}}/` — check what exists
+1. `{{RUNTIME_HELPER_CMD}} artifact list .prizmkit/specs/{{FEATURE_SLUG}}` — check what exists
 2. If `context-snapshot.md` exists: open recovery prompt with `"Read .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md for project context and any Implementation Log/Review Notes from previous agents. Run git diff HEAD to see actual code changes already made. Do NOT re-read individual source files unless the File Manifest directs you to."` + only remaining steps + `model: "lite"`
 3. Max 2 retries per phase. After 2 failures, orchestrator completes the work directly and appends a Recovery Note to context-snapshot.md.

package/bundled/dev-pipeline/templates/sections/test-failure-recovery-agent.md

@@ -21,7 +21,7 @@ Use this protocol whenever the post-review PrizmKit Test gate fails. Its purpose
 
 ### Hard Round Cap (BLOCKING)
 
-After **6 total test-fix rounds**, STOP trial-and-error. Write failure-log listing all hypotheses tried. Switch to: read full relevant source section ONCE (via `grep -n`+`sed -n`, never full Read), understand control flow, rewrite failing block in one shot. Do NOT exceed 7 total rounds.
+After **6 total test-fix rounds**, STOP trial-and-error. Write failure-log listing all hypotheses tried. Switch to: locate an anchor with `{{RUNTIME_HELPER_CMD}} text search <file> --pattern "<anchor>" --json`, read one bounded relevant source section with the platform file-reading tool (never full Read), understand control flow, rewrite failing block in one shot. Do NOT exceed 7 total rounds.
 
 ### Success Rule
 

package/bundled/dev-pipeline/templates/sections/test-failure-recovery-lite.md

@@ -21,7 +21,7 @@ Use this protocol whenever the post-review PrizmKit Test gate fails. Its purpose
 
 ### Hard Round Cap (BLOCKING)
 
-After **6 total test-fix rounds**, STOP trial-and-error. Write failure-log listing all hypotheses tried. Switch to: read full relevant source section ONCE (via `grep -n`+`sed -n`, never full Read), understand control flow, rewrite failing block in one shot. Do NOT exceed 7 total rounds.
+After **6 total test-fix rounds**, STOP trial-and-error. Write failure-log listing all hypotheses tried. Switch to: locate an anchor with `{{RUNTIME_HELPER_CMD}} text search <file> --pattern "<anchor>" --json`, read one bounded relevant source section with the platform file-reading tool (never full Read), understand control flow, rewrite failing block in one shot. Do NOT exceed 7 total rounds.
 
 ### Success Rule
 

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

@@ -444,7 +444,8 @@ class TestScopedFeatureTestGate:
 
         rendered = "\n".join(content for _, content in sections)
         assert "prizmkit-test-gate.py" not in rendered
-        assert ".prizmkit-test-started" in rendered
+        assert "{{RUNTIME_HELPER_CMD}} artifact touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started" in rendered
+        assert "mkdir -p .prizmkit/specs/{{FEATURE_SLUG}}" not in rendered
         assert "when present" not in rendered
         assert "Boundary Matrix" in rendered
         assert "Boundary Completion Gate" in rendered
@@ -474,7 +475,8 @@ class TestScopedFeatureTestGate:
         rendered = "\n".join(content for _, content in sections)
 
         assert "### Checkpoint Update Helper" in rendered
-        assert "python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py" in rendered
+        assert "{{CHECKPOINT_PYTHON_CMD}}" in rendered
+        assert "python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py" not in rendered
         assert "--checkpoint-path {{CHECKPOINT_PATH}}" in rendered
         assert "--step <step-id-or-skill-name>" in rendered
         assert "Do not hand-edit `workflow-checkpoint.json` directly." in rendered
@@ -1016,7 +1018,7 @@ def _write_feature_list(path, feature):
     path.write_text(json.dumps({"features": [feature], "global_context": {"language": "Python"}}), encoding="utf-8")
 
 
-def _render_feature_prompt(tmp_path, mode="standard", critic=False, template=None, platform="claude"):
+def _render_feature_prompt(tmp_path, mode="standard", critic=False, template=None, platform="claude", browser_interaction=None):
     project = tmp_path / "project"
     project.mkdir(parents=True)
     (project / ".prizmkit" / "plans").mkdir(parents=True)
@@ -1036,6 +1038,8 @@ def _render_feature_prompt(tmp_path, mode="standard", critic=False, template=Non
         "acceptance_criteria": ["Prompts are clean"],
         "critic": critic,
     }
+    if browser_interaction is not None:
+        feature["browser_interaction"] = browser_interaction
     feature_list = project / ".prizmkit" / "plans" / "feature-list.json"
     _write_feature_list(feature_list, feature)
     output = project / "prompt.md"
@@ -1208,6 +1212,9 @@ class TestHeadlessPromptCleanupF033:
             if "Feature ID" in prompt:
                 assert "/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/123-prompt-cleanup/" in prompt
                 assert ".prizmkit-test-started" in prompt
+                assert "{{RUNTIME_HELPER_CMD}}" not in prompt
+                assert "prizmkit-runtime-helper.py" in prompt
+            assert "python3 {{INIT_SCRIPT_PATH}}" not in prompt
 
     def test_legacy_feature_templates_are_clean_when_rendered(self, tmp_path):
         for template, mode in (("bootstrap-tier1.md", "lite"), ("bootstrap-tier2.md", "standard"), ("bootstrap-tier3.md", "full")):
@@ -1215,7 +1222,42 @@ class TestHeadlessPromptCleanupF033:
             for forbidden in HEADLESS_FORBIDDEN_PROMPT_STRINGS:
                 assert forbidden not in prompt
             assert "prizmkit-test-gate.py" not in prompt
+            assert "python3 {{INIT_SCRIPT_PATH}}" not in prompt
+            assert "which playwright-cli" not in prompt
+            assert "lsof -ti" not in prompt
+            assert "sed -nE" not in prompt
             assert ".prizmkit-test-started" in prompt
+            assert "{{RUNTIME_HELPER_CMD}}" not in prompt
+            assert "prizmkit-runtime-helper.py" in prompt
+
+    def test_legacy_feature_templates_with_browser_blocks_are_shell_free(self, tmp_path):
+        forbidden = [
+            "python3 {{INIT_SCRIPT_PATH}}",
+            "which playwright-cli",
+            "which opencli",
+            "lsof -ti",
+            "sed -nE",
+            "SKILL_DIR",
+            "DEV_SERVER_PID",
+            "opencli doctor 2>/dev/null ||",
+            "echo \"=== playwright-cli ===\" &&",
+        ]
+        cases = [
+            ("bootstrap-tier1.md", "lite"),
+            ("bootstrap-tier2.md", "standard"),
+            ("bootstrap-tier3.md", "full"),
+        ]
+        for template, mode in cases:
+            prompt = _render_feature_prompt(
+                tmp_path / f"browser-{template}",
+                mode=mode,
+                critic=(mode != "lite"),
+                template=template,
+                browser_interaction={"tool": "auto", "verify_steps": ["Open the page"]},
+            )
+            assert "prizmkit-runtime-helper.py" in prompt
+            for snippet in forbidden:
+                assert snippet not in prompt
 
     def test_claude_config_wins_over_codex_directory_for_critic_path(self, tmp_path, monkeypatch):
         project = tmp_path / "mixed"
@@ -1287,3 +1329,110 @@ class TestHeadlessPromptCleanupF033:
         monkeypatch.setenv("PRIZMKIT_PLATFORM", "codex")
 
         assert resolve_prompt_platform(str(project)) == "codex"
+
+
+
+class TestFeatureBootstrapShellExtraction:
+    RETIRED_EXTRACTED_SNIPPETS = [
+        "find . -maxdepth",
+        "| sed",
+        "grep -c '^\\- \\[ \\]'",
+        "grep -r \"123-prompt-cleanup\"",
+        "2>/dev/null",
+        "/dev/null",
+        "$DEV_PORT",
+        "$!",
+        "$HOME",
+        "if [ ",
+        "which playwright-cli",
+        "which opencli",
+        "lsof -ti",
+        "xargs",
+        " kill -",
+        "kill -",
+        "|| echo",
+        "grep -q '^/binary-name$'",
+        "echo '/binary-name' >> .gitignore",
+        "git log --oneline | grep",
+        "grep -n ",
+        "sed -n",
+        "wc -l",
+        "opencli browser open http://localhost:<DEV_PORT> && opencli browser state",
+        "opencli browser type 3 \"hello\" && opencli browser click 7",
+    ]
+
+    @staticmethod
+    def assert_shell_extracted_operations_removed(prompt):
+        for snippet in TestFeatureBootstrapShellExtraction.RETIRED_EXTRACTED_SNIPPETS:
+            assert snippet not in prompt
+        assert "{{RUNTIME_HELPER_CMD}}" not in prompt
+        assert "python" in prompt.lower()
+        assert ".prizmkit/dev-pipeline/scripts/prizmkit-runtime-helper.py" in prompt
+        assert "artifact touch .prizmkit/specs/123-prompt-cleanup/.prizmkit-test-started" in prompt
+        assert "text contains .prizmkit/specs/123-prompt-cleanup/review-report.md --pattern \"## Verdict\"" in prompt
+
+    def test_rendered_section_feature_prompts_use_runtime_helper_not_extracted_bash(self, tmp_path):
+        for mode in ("lite", "standard", "full"):
+            prompt = _render_feature_prompt(
+                tmp_path / f"section-{mode}",
+                mode=mode,
+                critic=(mode != "lite"),
+                browser_interaction={"tool": "auto", "verify_steps": ["Open the page"]},
+            )
+
+            self.assert_shell_extracted_operations_removed(prompt)
+            assert "executable version playwright-cli --arg=--version" in prompt
+            assert "executable version opencli --arg=--version" in prompt
+            assert "process start --pid-file .prizmkit/state/browser-dev-server.pid" in prompt
+            assert "process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>" in prompt
+            assert "port check <DEV_PORT>" in prompt or "port check 3000" in prompt
+
+    def test_rendered_legacy_tier_feature_prompts_use_runtime_helper_not_extracted_bash(self, tmp_path):
+        cases = [
+            ("bootstrap-tier1.md", "lite"),
+            ("bootstrap-tier2.md", "standard"),
+            ("bootstrap-tier3.md", "full"),
+        ]
+        for template, mode in cases:
+            prompt = _render_feature_prompt(
+                tmp_path / f"legacy-{template}",
+                mode=mode,
+                critic=(mode != "lite"),
+                template=template,
+                browser_interaction={"tool": "playwright-cli", "verify_steps": ["Open the page"]},
+            )
+
+            self.assert_shell_extracted_operations_removed(prompt)
+            assert "process start --pid-file .prizmkit/state/browser-dev-server.pid" in prompt
+            assert "process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>" in prompt
+            assert "port check 3000" in prompt
+
+    def test_legacy_tier_specific_extracted_operations_map_to_helper_commands(self, tmp_path):
+        tier1 = _render_feature_prompt(
+            tmp_path / "legacy-tier1-helper-map",
+            mode="lite",
+            template="bootstrap-tier1.md",
+        )
+        assert "artifact tree . --max-depth 2" in tier1
+        assert "text contains .gitignore --pattern \"/binary-name\"" in tier1
+        assert "NEEDS_IGNORE_ENTRY" in tier1
+
+        tier2 = _render_feature_prompt(
+            tmp_path / "legacy-tier2-helper-map",
+            mode="standard",
+            critic=True,
+            template="bootstrap-tier2.md",
+        )
+        assert "artifact exists .prizmkit/specs/123-prompt-cleanup/failure-log.md" in tier2
+        assert "artifact tree . --max-depth 2" in tier2
+        assert "text count .prizmkit/specs/123-prompt-cleanup/plan.md --pattern \"- [ ]\"" in tier2
+
+        tier3 = _render_feature_prompt(
+            tmp_path / "legacy-tier3-helper-map",
+            mode="full",
+            critic=True,
+            template="bootstrap-tier3.md",
+        )
+        assert "text search . --pattern \"123-prompt-cleanup\" --json" in tier3
+        assert "text count .prizmkit/specs/123-prompt-cleanup/plan.md --pattern \"- [ ]\"" in tier3
+        assert "Check if feature already committed by inspecting recent git history" in tier3

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

@@ -201,8 +201,9 @@ class TestExplicitProjectRoot:
         assert "{{" + REMOVED_MAX_LOG_ENV + "}}" not in replacements
         assert "{{" + REMOVED_MAX_LOG_HUMAN + "}}" not in replacements
         assert "### Checkpoint Update Helper" in replacements["{{CHECKPOINT_SYSTEM}}"]
-        assert "python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py" 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}}"]
 
 
 # ---------------------------------------------------------------------------

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

@@ -129,8 +129,9 @@ class TestExplicitProjectRoot:
         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 "python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py" 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:

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"

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

@@ -1904,6 +1904,9 @@ def test_materialize_worktree_support_assets_copies_ignored_assets_without_retir
     (repo / ".prizmkit" / "manifest.json").write_text("{}", encoding="utf-8")
     (repo / ".prizmkit" / "dev-pipeline" / "scripts").mkdir(parents=True)
     (repo / ".prizmkit" / "dev-pipeline" / "scripts" / "update-checkpoint.py").write_text("# update", encoding="utf-8")
+    (repo / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime").mkdir(parents=True)
+    (repo / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime" / "__init__.py").write_text("", encoding="utf-8")
+    (repo / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime" / "runtime_helper.py").write_text("# helper", encoding="utf-8")
     (repo / ".prizmkit" / "dev-pipeline" / "run-feature.sh").write_text("retired", encoding="utf-8")
 
     runtime = worktree_runtime_context(
@@ -1922,6 +1925,8 @@ def test_materialize_worktree_support_assets_copies_ignored_assets_without_retir
     assert (runtime.worktree_path / ".prizmkit" / "config.json").is_file()
     assert (runtime.worktree_path / ".prizmkit" / "manifest.json").is_file()
     assert (runtime.worktree_path / ".prizmkit" / "dev-pipeline" / "scripts" / "update-checkpoint.py").is_file()
+    assert (runtime.worktree_path / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime" / "__init__.py").is_file()
+    assert (runtime.worktree_path / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime" / "runtime_helper.py").is_file()
     assert not (runtime.worktree_path / ".prizmkit" / "dev-pipeline" / "run-feature.sh").exists()
 
     assert guarded_worktree_remove(runtime, delete_branch=False).ok

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.108",
+  "version": "1.1.110",
   "skills": {
     "prizmkit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.108",
+  "version": "1.1.110",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {