fix(#829): enforce repository-wide runtime launch choke point

packages/coord/src/__tests__/runtime-launch-gate.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveLaunchCommand } from '../runner.js';
+
+describe('coord consequential-runtime launch gate', () => {
+  it('routes default and direct configured Claude commands through mosaic', () => {
+    expect(resolveLaunchCommand('claude', 'continue', undefined)).toEqual([
+      'mosaic',
+      'claude',
+      '-p',
+      'continue',
+    ]);
+    expect(resolveLaunchCommand('claude', 'continue', ['claude', '-p', '{prompt}'])).toEqual([
+      'mosaic',
+      'claude',
+      '-p',
+      'continue',
+    ]);
+  });
+
+  it('preserves an already-gated Claude command and rejects unknown launchers', () => {
+    expect(
+      resolveLaunchCommand('claude', 'continue', ['mosaic', 'yolo', 'claude', '{prompt}']),
+    ).toEqual(['mosaic', 'yolo', 'claude', 'continue']);
+    expect(() => resolveLaunchCommand('claude', 'continue', ['custom-launcher'])).toThrow(
+      /must use `mosaic claude`/,
+    );
+  });
+
+  it('does not change the out-of-scope Codex command contract', () => {
+    expect(resolveLaunchCommand('codex', 'continue', undefined)).toEqual([
+      'codex',
+      '-p',
+      'continue',
+    ]);
+    expect(resolveLaunchCommand('codex', 'continue', ['codex', '{prompt}'])).toEqual([
+      'codex',
+      'continue',
+    ]);
+  });
+});

packages/coord/src/runner.ts

@@ -179,32 +179,41 @@ function buildContinuationPrompt(params: {
     `3. Read \`${mission.scratchpadFile}\` for session history and decisions`,
     `4. Read \`${mission.tasksFile}\` for current task state`,
     '5. `git pull --rebase` to sync latest changes',
-    `6. Launch runtime with \`${runtime} -p\``,
+    `6. Launch runtime with \`mosaic ${runtime} -p\``,
     `7. Continue execution from task **${taskId}**`,
     '8. Follow Two-Phase Completion Protocol',
     `9. You are the SOLE writer of \`${mission.tasksFile}\``,
   ].join('\n');
 }
 
-function resolveLaunchCommand(
+export function resolveLaunchCommand(
   runtime: 'claude' | 'codex',
   prompt: string,
   configuredCommand: string[] | undefined,
 ): string[] {
   if (configuredCommand === undefined || configuredCommand.length === 0) {
-    return [runtime, '-p', prompt];
+    return runtime === 'claude' ? ['mosaic', 'claude', '-p', prompt] : [runtime, '-p', prompt];
   }
 
   const hasPromptPlaceholder = configuredCommand.some((value) => value === '{prompt}');
   const withInterpolation = configuredCommand.map((value) =>
     value === '{prompt}' ? prompt : value,
   );
+  const command = hasPromptPlaceholder ? withInterpolation : [...withInterpolation, prompt];
 
-  if (hasPromptPlaceholder) {
-    return withInterpolation;
+  if (runtime !== 'claude') return command;
+  if (
+    command[0] === 'mosaic' &&
+    (command[1] === 'claude' || (command[1] === 'yolo' && command[2] === 'claude'))
+  ) {
+    return command;
   }
-
-  return [...withInterpolation, prompt];
+  if (command[0] === 'claude') {
+    return ['mosaic', 'claude', ...command.slice(1)];
+  }
+  throw new Error(
+    'Custom Claude task commands must use `mosaic claude` so lease registration cannot be bypassed.',
+  );
 }
 
 async function writeAtomicJson(filePath: string, payload: unknown): Promise<void> {

packages/mosaic/framework/guides/ORCHESTRATOR.md

@@ -3,7 +3,7 @@
 When spawning workers, include skill loading in the kickstart:
 
 ```bash
-claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."codex exec "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
+mosaic claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."codex exec "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
 ```
 
 #### **MANDATORY**

packages/mosaic/framework/tools/lease-broker/check-runtime-launches.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Fail CI when production code launches Claude/Pi outside the lease gate."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Final, NamedTuple, Sequence
+
+SCANNED_ROOTS: Final = ("packages", "apps", "plugins", "tools")
+SCANNED_SUFFIXES: Final = {
+    ".bash",
+    ".cjs",
+    ".js",
+    ".json",
+    ".mjs",
+    ".py",
+    ".sh",
+    ".ts",
+    ".tsx",
+    ".yaml",
+    ".yml",
+    ".zsh",
+}
+SKIPPED_DIRECTORIES: Final = {
+    ".git",
+    ".next",
+    ".turbo",
+    "coverage",
+    "dist",
+    "node_modules",
+}
+
+# A launch line is gated only when it names the common wrapper, the TypeScript
+# adapter that invokes that wrapper, or the `mosaic` runtime command that reaches
+# the adapter. Merely mentioning a session ID or hook is not sufficient.
+GATED_PATTERNS: Final = (
+    re.compile(r"\bexecLeaseGatedRuntime\s*\("),
+    re.compile(r"\blaunch-runtime\.(?:sh|py)\b"),
+    re.compile(
+        r"(?:\bexec\s+|\b(?:LAUNCH_COMMAND|launch_cmd)\s*=\s*\(?|\becho\s+[\"'])"
+        r"mosaic\s+(?:yolo\s+)?(?:claude|pi|claudex|[\"']?\$\{?runtime\}?[\"']?|[\"']?\$MOSAIC_AGENT_RUNTIME[\"']?)\b"
+    ),
+    re.compile(r"\[\s*[\"']mosaic[\"']\s*,\s*(?:[\"']yolo[\"']\s*,\s*)?(?:runtime|[\"'](?:claude|pi|claudex)[\"'])"),
+)
+
+DIRECT_PATTERNS: Final = (
+    # Shell/process command forms, including here-doc command examples that an
+    # operator could execute verbatim.
+    re.compile(r"^\s*(?:claude|pi)(?:\s|$)"),
+    re.compile(r"(?:^|[;&|]\s*|\bexec\s+|\bcommand\s+)(?:claude|pi)\s+(?:-p\b|--dangerously\b|--print\b)"),
+    re.compile(r"\bexec\s+(?:claude|pi)(?:\s|$)"),
+    re.compile(r"\bexec\s+(?:/[^\s/]+)+/(?:claude|pi)(?:\s|$)"),
+    re.compile(r"\bexec\s+[\"']?\$(?:\{?runtime\}?|MOSAIC_AGENT_RUNTIME)\b"),
+    # JS/TS and Python process APIs with a literal runtime binary.
+    re.compile(
+        r"\b(?:spawn|spawnSync|exec|execSync|execFile|execFileSync|execv|execvp|execvpe|Popen|run|call|system|check_call|check_output)\s*\(\s*(?:\[\s*)?[\"'](?:claude|pi)(?:[\"']|\s)"
+    ),
+    re.compile(
+        r"\b(?:spawn|spawnSync|exec|execSync|execFile|execFileSync|execv|execvp|execvpe|Popen|run|call|system|check_call|check_output)\s*\(\s*(?:\[\s*)?[\"'](?:/[^\"'/]+)+/(?:claude|pi)[\"']"
+    ),
+    # Launch-command arrays and the prior @mosaicstack/coord dynamic default.
+    re.compile(r"\b(?:spawn|spawnSync|exec|execSync|execFile|execFileSync)\s*\(\s*runtime\b"),
+    re.compile(r"\b(?:command|launchCommand|LAUNCH_COMMAND)\s*=\s*(?:\(|\[)\s*[\"']?(?:claude|pi)\b"),
+    re.compile(r"\b(?:command|launchCommand|LAUNCH_COMMAND)\s*=\s*(?:\(|\[)\s*[\"']?\$(?:\{?runtime\}?|MOSAIC_AGENT_RUNTIME)\b"),
+    re.compile(r"\breturn\s*\[\s*runtime\s*,\s*[\"'](?:-p|--dangerously)"),
+)
+
+
+class LaunchSite(NamedTuple):
+    path: Path
+    line_number: int
+    line: str
+    classification: str
+
+
+def is_test_path(path: Path) -> bool:
+    name = path.name.lower()
+    return (
+        "__tests__" in path.parts
+        or ".spec." in name
+        or ".test." in name
+        or name.endswith("_unittest.py")
+        or name.startswith("test-")
+        or name.startswith("test_")
+    )
+
+
+def is_gated_line(line: str) -> bool:
+    return any(pattern.search(line) for pattern in GATED_PATTERNS)
+
+
+def is_direct_line(line: str) -> bool:
+    return any(pattern.search(line) for pattern in DIRECT_PATTERNS)
+
+
+def scan_text(path: Path, source: str) -> list[LaunchSite]:
+    violations: list[LaunchSite] = []
+    gated_continuation = False
+    for line_number, line in enumerate(source.splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith(("#", "//", "*")):
+            gated_continuation = False
+            continue
+        gated = is_gated_line(line) or gated_continuation
+        if is_direct_line(line) and not gated:
+            violations.append(LaunchSite(path, line_number, line.rstrip(), "direct"))
+        gated_continuation = gated and line.rstrip().endswith("\\")
+    return violations
+
+
+def source_files(root: Path):
+    for relative_root in SCANNED_ROOTS:
+        search_root = root / relative_root
+        if not search_root.is_dir():
+            continue
+        for path in search_root.rglob("*"):
+            if not path.is_file() or path.suffix.lower() not in SCANNED_SUFFIXES:
+                continue
+            if any(part in SKIPPED_DIRECTORIES for part in path.parts):
+                continue
+            if is_test_path(path):
+                continue
+            yield path
+
+
+def scan_repository(root: Path) -> list[LaunchSite]:
+    violations: list[LaunchSite] = []
+    for path in source_files(root):
+        try:
+            source = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            violations.append(LaunchSite(path, 0, "non-UTF-8 source", "unscannable"))
+            continue
+        violations.extend(scan_text(path.relative_to(root), source))
+    return violations
+
+
+def inventory_repository(root: Path) -> list[LaunchSite]:
+    inventory: list[LaunchSite] = []
+    for path in source_files(root):
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except UnicodeDecodeError:
+            inventory.append(LaunchSite(path.relative_to(root), 0, "non-UTF-8 source", "unscannable"))
+            continue
+        gated_continuation = False
+        for line_number, line in enumerate(lines, start=1):
+            stripped = line.strip()
+            if not stripped or stripped.startswith(("#", "//", "*")):
+                gated_continuation = False
+                continue
+            line_is_gated = is_gated_line(line)
+            gated = line_is_gated or gated_continuation
+            if line_is_gated and not stripped.startswith("function execLeaseGatedRuntime"):
+                inventory.append(
+                    LaunchSite(path.relative_to(root), line_number, line.rstrip(), "gated")
+                )
+            elif is_direct_line(line) and not gated:
+                inventory.append(
+                    LaunchSite(path.relative_to(root), line_number, line.rstrip(), "direct")
+                )
+            gated_continuation = gated and line.rstrip().endswith("\\")
+    return inventory
+
+
+def format_violation(violation: LaunchSite) -> str:
+    return f"{violation.path}:{violation.line_number}: {violation.classification}: {violation.line.strip()}"
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--json", action="store_true")
+    arguments = parser.parse_args(argv)
+    root = arguments.root.resolve()
+    inventory = inventory_repository(root)
+    violations = [site for site in inventory if site.classification != "gated"]
+
+    if arguments.json:
+        print(
+            json.dumps(
+                {
+                    "gated": sum(site.classification == "gated" for site in inventory),
+                    "total": len(inventory),
+                    "sites": [
+                        {
+                            "path": str(site.path),
+                            "line": site.line_number,
+                            "classification": site.classification,
+                            "source": site.line.strip(),
+                        }
+                        for site in inventory
+                    ],
+                },
+                sort_keys=True,
+            )
+        )
+    else:
+        for site in inventory:
+            print(format_violation(site))
+        print(
+            f"runtime launch inventory: "
+            f"{len(inventory) - len(violations)} gated/{len(inventory)} total"
+        )
+
+    if violations:
+        print("ungated consequential runtime launch detected", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

packages/mosaic/framework/tools/orchestrator-matrix/adapters/README.md

@@ -32,7 +32,7 @@ Claude:
 ```json
 {
   "worker": {
-    "command_template": "claude -p \"Execute task {task_id}: {task_title}\""
+    "command_template": "mosaic claude -p \"Execute task {task_id}: {task_title}\""
   }
 }
 ```

packages/mosaic/framework/tools/prdy/prdy-init.sh

@@ -86,7 +86,8 @@ echo ""
 
 cd "$PROJECT"
 if [[ "$RUNTIME_CMD" == "claude" ]]; then
-  exec claude --dangerously-skip-permissions --append-system-prompt "$SYSTEM_PROMPT" "$KICKOFF"
+  exec python3 "$SCRIPT_DIR/../lease-broker/launch-runtime.py" --runtime claude -- \
+    claude --dangerously-skip-permissions --append-system-prompt "$SYSTEM_PROMPT" "$KICKOFF"
 fi
 
 if [[ "$RUNTIME_CMD" == "codex" ]]; then

packages/mosaic/framework/tools/prdy/prdy-update.sh

@@ -74,7 +74,8 @@ echo ""
 
 cd "$PROJECT"
 if [[ "$RUNTIME_CMD" == "claude" ]]; then
-  exec claude --dangerously-skip-permissions --append-system-prompt "$SYSTEM_PROMPT" "$KICKOFF"
+  exec python3 "$SCRIPT_DIR/../lease-broker/launch-runtime.py" --runtime claude -- \
+    claude --dangerously-skip-permissions --append-system-prompt "$SYSTEM_PROMPT" "$KICKOFF"
 fi
 
 if [[ "$RUNTIME_CMD" == "codex" ]]; then

packages/mosaic/framework/tools/qa/qa-hook-handler.sh

@@ -190,7 +190,7 @@ Pending QA validation
 This report was created by the QA automation hook.
 To process this report, run:
 \`\`\`bash
-claude -p "Use Task tool to launch universal-qa-agent for report: $REPORT_PATH"
+python3 ~/.config/mosaic/tools/lease-broker/launch-runtime.py --runtime claude -- claude -p "Use Task tool to launch universal-qa-agent for report: $REPORT_PATH"
 \`\`\`
 EOF
 

packages/mosaic/framework/tools/qa/remediation-hook-handler.sh

@@ -58,8 +58,8 @@ ACTIONS_PATH="$IN_PROGRESS_DIR/$ACTIONS_FILE"
 
 echo "[$(date '+%Y-%m-%d %H:%M:%S')] Starting remediation: $ACTIONS_PATH" | tee -a "$LOG_FILE"
 
-# Trigger remediation agent
-claude -p "Use Task tool to launch auto-remediation-agent for:
+# Trigger remediation agent through the authenticated lease-broker choke-point.
+python3 "$(dirname "$0")/../lease-broker/launch-runtime.py" --runtime claude -- claude -p "Use Task tool to launch auto-remediation-agent for:
 - Remediation Report: $IN_PROGRESS_DIR/$(basename "$REPORT_FILE")
 - Actions File: $ACTIONS_PATH
 - Max Iterations: 5

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/codex/test-pr-diff-context.sh"
+    "test:framework-shell": "python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

packages/mosaic/src/mutator-gate/runtime_launch_guard_unittest.py

@@ -4,8 +4,15 @@
 from __future__ import annotations
 
 import importlib.util
+import io
+import json
+import runpy
+import sys
+import tempfile
 import unittest
+from contextlib import redirect_stderr, redirect_stdout
 from pathlib import Path
+from unittest.mock import patch
 
 
 MOSAIC_ROOT = Path(__file__).parents[2]
@@ -26,6 +33,15 @@ class RuntimeLaunchGuardTest(unittest.TestCase):
             "typescript.ts": "spawn('pi', ['--print', prompt]);\n",
             "python.py": "subprocess.run(['claude', '-p', prompt])\n",
             "dynamic.ts": "return [runtime, '-p', prompt];\n",
+            "plain-shell.sh": 'claude "$prompt"\n',
+            "node-exec.ts": 'exec("claude --print hello");\n',
+            "command-array.ts": "const launchCommand = ['pi', '--print', prompt];\n",
+            "python-system.py": 'os.system("claude -p prompt")\n',
+            "dynamic-shell.sh": 'exec "$runtime" "$prompt"\n',
+            "dynamic-spawn.ts": 'spawn(runtime, args);\n',
+            "dynamic-command.sh": 'LAUNCH_COMMAND=("$MOSAIC_AGENT_RUNTIME" --print)\n',
+            "absolute-shell.sh": 'exec /usr/local/bin/claude -p prompt\n',
+            "absolute-spawn.ts": "spawn('/opt/bin/pi', args);\n",
         }
         for filename, source in cases.items():
             with self.subTest(filename=filename):
@@ -51,6 +67,68 @@ class RuntimeLaunchGuardTest(unittest.TestCase):
             "\n".join(GUARD.format_violation(violation) for violation in violations),
         )
 
+    def test_repository_walk_skips_tests_build_outputs_and_reports_unscannable_source(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            production = root / "packages/example/src/launch.sh"
+            production.parent.mkdir(parents=True)
+            production.write_text("exec claude -p prompt\n")
+            (production.parent / "launch.spec.ts").write_text("spawn('pi', [])\n")
+            dist = root / "packages/example/dist/launch.js"
+            dist.parent.mkdir(parents=True)
+            dist.write_text("exec('claude -p prompt')\n")
+            ignored_suffix = production.parent / "notes.txt"
+            ignored_suffix.write_text("claude -p prompt\n")
+            invalid = production.parent / "invalid.py"
+            invalid.write_bytes(b"\xff\xfe")
+
+            violations = GUARD.scan_repository(root)
+            formatted = [GUARD.format_violation(item) for item in violations]
+            self.assertEqual(len(violations), 2)
+            self.assertTrue(any("launch.sh:1: direct" in item for item in formatted))
+            self.assertTrue(any("invalid.py:0: unscannable" in item for item in formatted))
+            self.assertFalse(any("spec" in item or "dist" in item or "notes" in item for item in formatted))
+
+            inventory = GUARD.inventory_repository(root)
+            self.assertEqual({item.classification for item in inventory}, {"direct", "unscannable"})
+
+    def test_main_emits_machine_inventory_and_fails_on_a_direct_site(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            source = root / "packages/example/launch.sh"
+            source.parent.mkdir(parents=True)
+            source.write_text("exec claude -p prompt\n")
+            stdout = io.StringIO()
+            stderr = io.StringIO()
+            with redirect_stdout(stdout), redirect_stderr(stderr):
+                result = GUARD.main(["--root", str(root), "--json"])
+            payload = json.loads(stdout.getvalue())
+            self.assertEqual(result, 1)
+            self.assertEqual(payload["gated"], 0)
+            self.assertEqual(payload["total"], 1)
+            self.assertIn("ungated consequential runtime", stderr.getvalue())
+
+    def test_main_text_mode_reports_a_green_gated_inventory(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            source = root / "packages/example/launch.sh"
+            source.parent.mkdir(parents=True)
+            source.write_text("exec mosaic yolo claude prompt\n")
+            stdout = io.StringIO()
+            with redirect_stdout(stdout):
+                result = GUARD.main(["--root", str(root)])
+            self.assertEqual(result, 0)
+            self.assertIn("1 gated/1 total", stdout.getvalue())
+
+    def test_script_entrypoint_uses_current_directory_default(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "packages").mkdir()
+            with patch.object(sys, "argv", [str(GUARD_PATH)]), patch("pathlib.Path.cwd", return_value=root):
+                with redirect_stdout(io.StringIO()), self.assertRaises(SystemExit) as raised:
+                    runpy.run_path(str(GUARD_PATH), run_name="__main__")
+            self.assertEqual(raised.exception.code, 0)
+
 
 if __name__ == "__main__":
     unittest.main()

packages/mosaic/src/mutator-gate/runtime_tools_unittest.py

@@ -6,7 +6,10 @@ from __future__ import annotations
 import importlib.util
 import io
 import json
+import os
+import runpy
 import socket
+import sys
 import unittest
 from contextlib import redirect_stderr
 from pathlib import Path
@@ -97,6 +100,17 @@ class LaunchRuntimeTest(unittest.TestCase):
         self.assertEqual(environment["MOSAIC_LEASE_RUNTIME"], "claude")
         self.assertEqual(environment["PRESERVED"], "yes")
 
+    def test_command_without_separator_is_forwarded_unchanged(self) -> None:
+        executed: list[tuple[str, list[str], dict[str, str]]] = []
+        result = LAUNCHER.main(
+            ["--runtime", "pi", "pi", "--print", "hello"],
+            environ={"MOSAIC_LEASE_BROKER_SOCKET": "/broker"},
+            request=lambda *_args: {"ok": True, "session_id": "f" * 64},
+            execute=lambda *args: executed.append(args),
+        )
+        self.assertEqual(result, 0)
+        self.assertEqual(executed[0][0:2], ("pi", ["pi", "--print", "hello"]))
+
     def test_missing_command_is_usage_error(self) -> None:
         with redirect_stderr(io.StringIO()):
             self.assertEqual(
@@ -185,6 +199,31 @@ class LaunchRuntimeTest(unittest.TestCase):
                         self.assertEqual(fake.shutdown_how, socket.SHUT_WR)
 
 
+class ExecutableEntrypointTest(unittest.TestCase):
+    def test_launcher_entrypoint_returns_usage_without_a_command(self) -> None:
+        with patch.object(
+            sys,
+            "argv",
+            [str(TOOLS_DIR / "launch-runtime.py"), "--runtime", "claude"],
+        ), redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as raised:
+            runpy.run_path(str(TOOLS_DIR / "launch-runtime.py"), run_name="__main__")
+        self.assertEqual(raised.exception.code, 64)
+
+    def test_gate_entrypoint_denies_when_identity_environment_is_absent(self) -> None:
+        class Stdin:
+            buffer = io.BytesIO(b'{"tool_name":"Bash"}')
+
+        with patch.object(
+            sys,
+            "argv",
+            [str(TOOLS_DIR / "mutator-gate.py"), "--runtime", "claude"],
+        ), patch.object(sys, "stdin", Stdin()), patch.dict(
+            os.environ, {}, clear=True
+        ), redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as raised:
+            runpy.run_path(str(TOOLS_DIR / "mutator-gate.py"), run_name="__main__")
+        self.assertEqual(raised.exception.code, 2)
+
+
 class MutatorGateTest(unittest.TestCase):
     @staticmethod
     def environment() -> dict[str, str]: